Merge remote-tracking branch 'origin/main' into berndverst-entity-method-signature-cache

Author: Bernd Verst

.github/copilot-instructions.md

@@ -2,19 +2,25 @@
 
 ## Project Overview
 
-This is the Durable Task Python SDK, providing a client and worker for
-building durable orchestrations. The repo contains two packages:
+This repository provides the Durable Task Python SDK and Azure Functions
+provider implementations for building durable orchestrations. It contains
+three packages:
 
 - `durabletask` — core SDK (in `durabletask/`)
 - `durabletask.azuremanaged` — Azure Durable Task Scheduler provider (in `durabletask-azuremanaged/`)
+- `azure-functions-durable` — Azure Durable Functions provider (in
+  `azure-functions-durable/`)
 
 ## Changelog Requirements
 
-- ALWAYS document user-facing changes in the appropriate changelog under
-  `## Unreleased`.
-- Update `CHANGELOG.md` for core SDK changes and
-  `durabletask-azuremanaged/CHANGELOG.md` for provider changes.
-- If a change affects both packages, update both changelogs.
+- ALWAYS document user-facing changes in the applicable changelog under
+  `## Unreleased`. Create that section if the changelog does not yet have one.
+- Update `CHANGELOG.md` for core SDK changes,
+  `durabletask-azuremanaged/CHANGELOG.md` for Durable Task Scheduler provider
+  changes, and `azure-functions-durable/CHANGELOG.md` for Azure Functions
+  provider changes.
+- If a change affects multiple packages, update each affected package's
+  changelog.
 - Include changelog entries for externally observable outcomes only, such as
   new public APIs, behavior changes, bug fixes users can notice, breaking
   changes, and new configuration capabilities.
@@ -24,8 +30,14 @@ building durable orchestrations. The repo contains two packages:
 - When in doubt, write the changelog entry in terms of user impact (what users
   can now do or what behavior changed), not implementation mechanism (how it
   was implemented internally).
+- Changelogs are not covered by the CI Markdown lint step. Review changes to
+  them manually.
+- Use the current unindented changelog style: category labels such as `ADDED`,
+  `CHANGED`, and `FIXED` are plain, unindented lines, and wrapped entry text
+  remains unindented rather than being aligned beneath the bullet.
 
 Examples:
+
 - Include: "Added `get_orchestration_history()` to retrieve orchestration history from the client."
 - Exclude: "Added internal helper functions to aggregate streamed history chunks."
 
@@ -61,10 +73,16 @@ priority over style.
 ## Python Linting
 
 This repository uses [flake8](https://flake8.pycqa.org/) for Python
-linting. Run it after making changes to verify there are no issues:
+linting. Run it after making changes to verify there are no issues. Lint
+package source and its tests separately, matching CI:
 
 ```bash
-python -m flake8 path/to/changed/file.py
+python -m flake8 durabletask
+python -m flake8 tests/durabletask
+python -m flake8 durabletask-azuremanaged
+python -m flake8 tests/durabletask-azuremanaged
+python -m flake8 azure-functions-durable
+python -m flake8 tests/azure-functions-durable
 ```
 
 ## Markdown Style
@@ -117,18 +135,42 @@ python -m pip install -r dev-requirements.txt
 
 ## Building and Testing
 
-Install the packages locally in editable mode:
+Use the repository-root `.venv` for core and Azure Managed development, and
+for Azure Functions Durable linting, type checking, and unit tests. The Azure
+Functions Durable package requires Python 3.13+, so use a 3.13+ root virtual
+environment for that work. Install packages locally in editable mode:
 
 ```bash
-python -m pip install -e . -e ./durabletask-azuremanaged
+python -m pip install -e . -e ./durabletask-azuremanaged \
+  -e ./azure-functions-durable
 ```
 
-Run tests with pytest:
+Run the applicable unit tests with pytest. Azure Functions Durable unit tests
+exclude tests that require an Azure Functions host or external services:
 
 ```bash
 python -m pytest
+python -m pytest tests/azure-functions-durable \
+  -m "not dts and not azurite and not functions_e2e"
+```
+
+Run Azure Functions Durable E2E tests through Nox, not directly from the root
+virtual environment. Nox creates an isolated Python 3.13 session environment,
+installs the local packages editable, and links it into each sample Function
+app so the Functions worker loads the app's grpc/protobuf dependencies. The
+suite requires Azure Functions Core Tools (`func`) on `PATH` and a running
+Azurite instance with blob storage on port 10000:
+
+```bash
+nox -s functions_e2e
 ```
 
+After the first successful run, use `nox -R -s functions_e2e` for E2E reruns.
+`-R` reuses the Nox environment and skips reinstalls; because the packages are
+editable, source changes are still picked up. Pass pytest selectors after `--`,
+for example `nox -R -s functions_e2e -- -k "dtask_client"`. Do not manually
+activate or modify the per-app `.venv` directories created by Nox.
+
 ## Project Structure
 
 - `durabletask/` — core SDK source
@@ -140,10 +182,23 @@ python -m pytest
   - `testing/` — in-memory backend for testing without a sidecar
   - `internal/` — protobuf definitions, gRPC helpers, tracing (not public API)
 - `durabletask-azuremanaged/` — Azure managed provider source
+- `azure-functions-durable/` — Azure Durable Functions provider source
 - `examples/` — example orchestrations (see `examples/README.md`)
 - `tests/` — test suite
 - `dev-requirements.txt` — development dependencies
 
+## External Dependencies
+
+The Azure Functions Durable provider integrates with APIs and runtime behavior
+owned by these repositories. Consult their current source when changing
+decorators, bindings, converters, or worker integration behavior:
+
+- [Azure Functions Python library](https://github.com/Azure/azure-functions-python-library)
+  — application, decorator, and binding APIs.
+- [Azure Functions Python worker](https://github.com/Azure/azure-functions-python-worker)
+  — function loading, binding conversion, dependency isolation, and invocation
+  behavior.
+
 ## Cross-Package Compatibility
 
 The `durabletask-azuremanaged` package extends the core `durabletask`

.github/skills/release-prep/SKILL.md

@@ -1,25 +1,31 @@
 ---
 name: release-prep
 description: >-
-  Prepare a release for durabletask and durabletask.azuremanaged. Use when the
-  user asks for release prep, version bumping, changelog updates, or release
-  body drafting. Trigger phrases include: release prep, prepare vX.Y.Z,
-  changelog for release, and draft GitHub release notes.
+  Prepare a release for durabletask, durabletask.azuremanaged, or
+  azure-functions-durable. Use when the user asks for release prep, version
+  bumping, changelog updates, or release body drafting. Trigger phrases include:
+  release prep, prepare vX.Y.Z, changelog for release, and draft GitHub release
+  notes.
 ---
 
 # Release Prep
 
-This skill prepares a coordinated release for both packages in this repository:
+This skill prepares a coordinated release for all packages in this repository:
 
 - `durabletask`
 - `durabletask.azuremanaged`
+- `azure-functions-durable`
 
 The skill accepts a target version (for example `1.4.0`) and performs the
-required changes consistently.
+required changes consistently. A single-package release is an exception: only
+release one package when the user explicitly requests it, and record that
+exception in the release-preparation instructions for that release.
 
 ## Inputs
 
 - `version`: Target semantic version (for example `1.4.0`)
+- Optional: `packages` limits the release to named packages only when the user
+  explicitly requests a single-package release.
 - Optional: `baseTag` overrides for comparison if tags are non-standard
 
 If `version` is not provided, ask the user before continuing.
@@ -30,31 +36,43 @@ If `version` is not provided, ask the user before continuing.
 
 - Root package range: `v<previousVersion>..HEAD`
 - Azure managed package range: `azuremanaged-v<previousVersion>..HEAD`
+- Azure Functions package range: `azurefunctions-v<previousVersion>..HEAD`
 - Use commit subjects and touched files to classify each change as:
   - `durabletask` only
   - `durabletask.azuremanaged` only
+  - `azure-functions-durable` only
   - shared/infra/docs changes
 
 ### 2. Update package versions
 
-Update both project versions:
+Update all project versions:
 
 - `pyproject.toml` -> `version = "<version>"`
 - `durabletask-azuremanaged/pyproject.toml` -> `version = "<version>"`
+- `azure-functions-durable/pyproject.toml` -> `version = "<version>"`
 
-Update azuremanaged dependency floors:
+Update Azure Managed dependency floors:
 
 - `durabletask>=<version>`
 - `durabletask[azure-blob-payloads]>=<version>`
 
+Update the `azure-functions-durable` `durabletask` dependency floor when the
+coordinated release establishes a new compatible core SDK minimum. For an
+explicit single-package Azure Functions release, do not change that floor
+solely because the provider package version changes.
+
 ### 3. Update changelogs
 
-- Add a new `## v<version>` section directly under `## Unreleased` in:
-  - `CHANGELOG.md`
-  - `durabletask-azuremanaged/CHANGELOG.md`
+- Add a new `## v<version>` section directly under `## Unreleased` in every
+  package's changelog. Create `## Unreleased` if it is absent:
+  - `CHANGELOG.md` for `durabletask`
+  - `durabletask-azuremanaged/CHANGELOG.md` for `durabletask.azuremanaged`
+  - `azure-functions-durable/CHANGELOG.md` for `azure-functions-durable`
 - Ensure user-facing changes since the previous release tags are represented.
 - Keep entries concise and grouped by type (`ADDED`, `CHANGED`, `FIXED`, `REMOVED`) where
   applicable.
+- Follow the repository's unindented changelog style. Changelogs are not
+  covered by CI Markdown linting, so review their formatting manually.
 - Exclude internal-only changes from changelogs (for example CI/workflow-only
   updates, test-only changes, and implementation refactors with no public
   behavior or API impact).
@@ -71,23 +89,26 @@ Before creating draft releases in GitHub UI, require explicit user
 confirmation of both conditions:
 
 - The version-bump/release-prep PR is merged
-- Tags `v<version>` and `azuremanaged-v<version>` already exist in the target
-  repository
+- Tags for every package already exist in the target repository:
+  `v<version>` for `durabletask`, `azuremanaged-v<version>` for
+  `durabletask.azuremanaged`, and `azurefunctions-v<version>` for
+  `azure-functions-durable`
 
 If either condition is not met, stop after preparing release body text and ask
 the user to confirm once merge and tags are complete.
 
 ### 6. Draft GitHub release bodies
 
-Draft two release body texts for the GitHub Releases UI (do not add files to
+Draft three release body texts for the GitHub Releases UI (do not add files to
 the repository):
 
-- Tag: `v<version>`
-- Tag: `azuremanaged-v<version>`
+- `durabletask`: `v<version>`
+- `durabletask.azuremanaged`: `azuremanaged-v<version>`
+- `azure-functions-durable`: `azurefunctions-v<version>`
 
 Match existing release structure:
 
-- Title (`# v<version>` or `# azuremanaged-v<version>`)
+- Title matching the package tag
 - `## What's Changed`
 - `## External Links`
 - `### Contributors`

README.md

@@ -6,21 +6,23 @@ MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/
 Validation](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml/badge.svg)](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml)
 [![PyPI version](https://badge.fury.io/py/durabletask.svg)](https://badge.fury.io/py/durabletask)
 
-This repo contains a Python SDK for use with the [Azure Durable Task
-Scheduler](https://github.com/Azure/Durable-Task-Scheduler). With this SDK, you can define,
-schedule, and manage durable orchestrations using ordinary Python code.
+This repository contains Python SDKs for building durable orchestrations with
+[Azure Durable Task Scheduler](https://github.com/Azure/Durable-Task-Scheduler)
+and [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/):
 
-> Note that this SDK is **not** currently compatible with [Azure Durable
-Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If
-you are looking for a Python SDK for Azure Durable Functions, please see [this
-repo](https://github.com/Azure/azure-functions-durable-python).
+- [`durabletask`](./durabletask/) is the core orchestration SDK.
+- [`durabletask.azuremanaged`](./durabletask-azuremanaged/) is the Azure Durable
+  Task Scheduler provider.
+- [`azure-functions-durable`](./azure-functions-durable/) is a preview Azure
+  Durable Functions provider built on `durabletask`.
 
 ## References
 
 - [Supported Patterns](./docs/supported-patterns.md)
 - [Available Features](./docs/features.md)
 - [Getting Started](./docs/getting-started.md)
 - [Development Guide](./docs/development.md)
+- [Azure Functions Durable 2.x](./azure-functions-durable/README.md)
 - [Contributing Guide](./CONTRIBUTING.md)
 
 ## Optional Features

azure-functions-durable/README.md

@@ -38,6 +38,9 @@ calls (`context.call_http(...)`), recurring scheduled tasks, and history export.
 - [Changelog](CHANGELOG.md)
 - [Durable Functions documentation](https://learn.microsoft.com/azure/azure-functions/durable/)
 - [`durabletask` on PyPI](https://pypi.org/project/durabletask/)
+- [Azure Functions Durable 1.x source](https://github.com/Azure/azure-functions-durable-python)
+- [Azure Functions Python library](https://github.com/Azure/azure-functions-python-library)
+- [Azure Functions Python worker](https://github.com/Azure/azure-functions-python-worker)
 - [Repository](https://github.com/microsoft/durabletask-python)
 
 ## License

durabletask-azuremanaged/CHANGELOG.md

@@ -14,6 +14,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `DefaultAzureCredential`) now surface from the first request rather than from the constructor.
   The exception type and message are unchanged; only the timing differs.
 - `FailureDetails.error_type` now carries the fully-qualified type name (e.g. `durabletask.task.TaskFailedError`) instead of the bare class name, and the new `FailureDetails.is_caused_by()` helper is available (both inherited from durabletask). See the core `durabletask` changelog for details, including the breaking-change notes.
+- Improved async access token refresh concurrency handling to avoid duplicate
+  refresh operations under concurrent access, matching the existing sync
+  behavior.
 
 ## v1.8.0
 

durabletask-azuremanaged/durabletask/azuremanaged/internal/access_token_manager.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
+import asyncio
 from datetime import datetime, timedelta, timezone
 from threading import Lock
 
@@ -71,9 +72,37 @@ def __init__(self, token_credential: AsyncTokenCredential | None,
         self._token = None
         self.expiry_time = None
 
+        # An asyncio.Lock binds itself to the event loop it is first used on, and this
+        # manager may outlive a loop or be shared across loops. Locks are therefore
+        # created lazily per running loop, guarded by a plain threading lock because
+        # different loops may run on different threads.
+        self._refresh_locks: dict[asyncio.AbstractEventLoop, asyncio.Lock] = {}
+        self._refresh_locks_guard = Lock()
+
+    def _get_refresh_lock(self) -> asyncio.Lock:
+        loop = asyncio.get_running_loop()
+        with self._refresh_locks_guard:
+            lock = self._refresh_locks.get(loop)
+            if lock is None:
+                # Discard locks belonging to loops that are no longer usable so the
+                # mapping does not grow without bound.
+                stale_loops = [
+                    existing for existing in self._refresh_locks if existing.is_closed()
+                ]
+                for stale_loop in stale_loops:
+                    del self._refresh_locks[stale_loop]
+                lock = asyncio.Lock()
+                self._refresh_locks[loop] = lock
+            return lock
+
     async def get_access_token(self) -> AccessToken | None:
         if self._token is None or self.is_token_expired():
-            await self.refresh_token()
+            async with self._get_refresh_lock():
+                # Re-check under the lock: a concurrent caller may have already
+                # refreshed the token while this one was waiting, so only a single
+                # credential request is made per refresh window.
+                if self._token is None or self.is_token_expired():
+                    await self.refresh_token()
         return self._token
 
     def is_token_expired(self) -> bool: