Allow Azure Functions Durable 2.x apps to opt in to JsonDataConverter

Summary

Add an app-wide opt-in for new azure-functions-durable 2.x applications to use durabletask.serialization.JsonDataConverter instead of the default Functions-compatible converter.

Proposed usage:

from durabletask.serialization import JsonDataConverter

app = df.DFApp(data_converter=JsonDataConverter())

Keep FunctionsDataConverter as the default for v1 compatibility.

Motivation

azure-functions-durable 2.x is built on durabletask, but currently hardcodes FunctionsDataConverter across workers, bound clients, compatibility wrappers, testing helpers, and activity binding conversion. New durabletask-native applications should be able to select durabletask's plain-JSON, type-directed serialization model consistently across every payload boundary.

Design constraints

• The setting must be function-app/process-wide, not per function or blueprint. Azure Functions uses one mutable binding-converter registry per Python worker process.
• Blueprints can be constructed before DFApp, so workers created during decoration must observe the later app-level selection.
• Activity input/output conversion happens in ActivityTriggerConverter, outside the durabletask worker pipeline. It must use the same converter as orchestrators, entities, and clients.
• The Functions worker does not pass activity parameter types to converter decode(). Activity wrappers must retain the original resolved type hint and apply converter coercion after binding decode.
• Only converters producing valid JSON are compatible with the activity binding wire contract. Initially restrict the option to JsonDataConverter subclasses or validate this contract explicitly.
• Preserve the activity converter's existing raw-string fallback.
• Conflicting app configurations in one process should fail immediately; repeated equivalent configuration should be idempotent.

A process-wide delegating DataConverter proxy is one possible implementation. Existing workers and cached clients can retain the stable proxy while DFApp selects its delegate before invocation.

Compatibility and migration safety

This opt-in should be documented for new task hubs only.

The current Functions codec can emit custom-object envelopes containing __class__, __module__, and __data__. JsonDataConverter emits plain JSON and does not reconstruct those envelopes. Switching an existing task hub can therefore break orchestration replay and persisted entity state. Entities may be long-lived and cannot simply be allowed to drain.

When the opt-in encounters a Functions custom-object envelope, it should fail loudly rather than silently returning the envelope as an ordinary dictionary.

The feature is primarily for durabletask-native authoring. V1-style activity calls that do not supply a result type may receive dictionaries for custom outputs under JsonDataConverter; document this limitation or provide an explicit typed path.

Implementation surfaces

• azure.durable_functions.decorators.DFApp and Blueprint
• DurableFunctionsWorker
• DurableFunctionsClient and SyncDurableFunctionsClient, including the process-wide sync-client cache
• ActivityTriggerConverter
• v1 orchestration/entity compatibility contexts
• entity testing helpers and other import-time converter captures
• built-in scheduled-task, history-export, and Durable HTTP registrations
• public documentation and azure-functions-durable/CHANGELOG.md

Acceptance criteria

• DFApp(data_converter=JsonDataConverter()) consistently applies the converter to client, orchestration, activity, entity, event, custom-status, and persisted-state payloads.
• Existing apps without the option retain current serialization behavior.
• Blueprints created before the app still use the selected converter.
• Conflicting process-wide selections fail with a clear error.
• Functions custom-object envelopes fail clearly under the opt-in.
• Activity raw-string fallback remains supported.
• Unit tests cover all serialization boundaries, compatibility wrappers, cached clients, configuration conflicts, and cross-format behavior.
• An end-to-end test round-trips typed dataclasses through client, orchestrator, activity, and entity paths.
• Documentation warns users to select the converter before creating data in a task hub and explains v1-style limitations.

Comece pela configuração de DFApp e Blueprint e, em seguida, acompanhe DurableFunctionsWorker, ambas as classes de cliente e o cache de sync-client em todo o processo para descobrir onde FunctionsDataConverter é capturado. Revise ActivityTriggerConverter e os contextos de compatibilidade e os helpers de teste; depois, adicione cobertura para a seleção de converters, conflitos, clientes em cache, limites de payload e os limites de migração documentados. O trabalho estará concluído quando JsonDataConverter for consistentemente opt-in e os apps existentes mantiverem o comportamento atual.