Add durable-functions@4.0.0 — Azure Functions Durable provider on the gRPC core (+ core host helpers, E2E CI, and release pipeline)

[YunchuWang]

TL;DR for reviewers

This PR began as "add two Functions gRPC helpers to the core worker" (the original title), but it now delivers the full Azure Functions Durable provider on the gRPC core. The headline change is a new npm package durable-functions@4.0.0 (packages/azure-functions-durable/, ~30 source files — does not exist on main) that re-implements the classic Durable Functions programming model on top of @microsoft/durabletask-js. It is the gRPC-core successor to the classic v3 (extension‑HTTP) durable-functions package and targets the @azure/functions v4 programming model. The core worker helpers, the E2E suite enablement, and the release pipeline are the supporting cast.

Scope: 58 files, +4,648 / −523, across four areas:

#	Area	What	Key paths
1	New provider package (the bulk)	durable-functions@4.0.0 on the gRPC core — v3‑compatible programming model	packages/azure-functions-durable/**
2	Core host helpers (original scope)	Single‑work‑item byte processors on TaskHubGrpcWorker	packages/durabletask-js/src/worker/task-hub-grpc-worker.ts, src/index.ts
3	E2E suite + CI	Wire the (pre‑existing) Functions host E2E suite to run green on PRs	.github/workflows/functions-e2e-tests.yaml, test/e2e-functions/**
4	Build & release	Pack + ESRP‑publish the new package	eng/templates/build.yml, eng/ci/release.yml

---

1. New package: durable-functions@4.0.0 (packages/azure-functions-durable/)

A v3‑API‑compatible Azure Functions Durable provider built on the gRPC core, so existing v3 orchestrator/activity/entity/client code type‑checks and runs against the consolidated gRPC path. Added whole in this PR (not on main).

• Registration surface (app.ts, app-client.ts, trigger.ts, input.ts, worker.ts): app.orchestration / app.activity / app.entity, the app.client.* durable‑client starter helpers (HTTP / timer / blob / queue / service‑bus / event‑hub / event‑grid / cosmos), and trigger + input bindings.
• Client (client.ts, 616 lines): DurableFunctionsClient / DurableOrchestrationClient — start, terminate, suspend, resume, raiseEvent, getStatus, purge, rewind, restart. Includes _mapControlPlaneError, which translates opaque gRPC control‑plane errors back to the v3 error surface (see Error fidelity below).
• Execution contexts (orchestration-context.ts, entity-context.ts): DurableOrchestrationContext / DurableEntityContext plus wrapOrchestrator / wrapEntity adapters bridging the classic generator model to the core.
• Status / query / types: orchestration-status.ts, orchestration-filter.ts, metadata.ts, retry-options.ts, entity-id.ts, entity-state-response.ts, purge-history-result.ts, http-management-payload.ts, get-client.ts, durable-grpc.ts, user-agent.ts.
• Top‑level v3 compat aliases: re‑exports TaskFailedError from core for instanceof guards; type aliases (DurableClient, EntityContext<T>, OrchestrationHandler, …) so v3 code compiles unchanged. README.md + CHANGELOG.md document migration notes and intentional omissions (DurableError / AggregatedError).
• ~15 unit spec files (~2,000 lines) covering client, client‑query, app, app‑client, orchestration‑context, entity‑context, query‑types, status, retry‑options, trigger, worker, get‑client, compat‑exports, durable‑grpc, entity‑id — 91/91 passing.

2. Core host helpers on TaskHubGrpcWorker (original PR scope)

Two methods that let a host drive one durable work item per invocation without the long‑lived gRPC worker loop — mirroring the Python consolidation in durabletask-python #155:

• processOrchestratorRequest(request: Uint8Array): Promise<Uint8Array>
• processEntityBatchRequest(request: Uint8Array): Promise<Uint8Array>

Each deserializes a TaskHubSidecarService protobuf, executes one work item via the worker's existing internal path (_executeOrchestratorInternal / _executeEntityInternal) using an in‑process CapturingSidecarStub (null‑stub pattern, same as Python's AzureFunctionsNullStub), and returns the serialized response. Transport encoding (e.g. base64) stays in the host, out of core. Covered by packages/durabletask-js/test/functions-grpc-support.spec.ts.

3. E2E suite + CI enablement

The Functions host E2E suite already exists on main; this PR makes it actually run — and pass — against the new provider:

• Workflow (.github/workflows/functions-e2e-tests.yaml): runs on pull_request for the Functions surface (test/e2e-functions/**, packages/azure-functions-durable/**, the workflow file) plus workflow_dispatch; adds --skipApiVersionCheck to Azurite; fixes build ordering; and fixes a latent invalid‑YAML step name that was blocking the workflow entirely (including manual dispatch).
• Test app (test/e2e-functions/test-app/host.json): targets the Preview extension bundle [4.29.0, 5.0.0) (gRPC path) and sets maxGrpcMessageSizeInBytes: 2147483647 to lift the host's default 4 MiB gRPC receive cap (which otherwise fails large‑output / get‑all‑instances). See Cross‑language note.
• Specs / harness: harness.ts expected‑error strings aligned to the v4 gRPC‑core fidelity; suspend-resume.spec.ts / terminate.spec.ts updated, with 3 terminal‑instance control‑plane cases skipped pending Functions v4 client: terminal/invalid-state control-plane ops surface opaque 2 UNKNOWN (HTTP 400) instead of a meaningful status #315.
• Docs / runner: README.md, test/e2e-functions/README.md, scripts/test-e2e-functions.sh.
• Result: 32 passed / 0 failed / 13 skipped (the 13 = 3 new Functions v4 client: terminal/invalid-state control-plane ops surface opaque 2 UNKNOWN (HTTP 400) instead of a meaningful status #315 skips + pre‑existing environment/feature skips).

4. Build & release pipeline

• eng/templates/build.yml: pack durable-functions and stage the azure-functions-durable artifact.
• eng/ci/release.yml: new durable_functions ESRP release job to publish the package.

---

Error fidelity (_mapControlPlaneError)

The consolidated gRPC path collapses control‑plane failures into two opaque codes; the compat layer translates them back to the v3 surface:

• NOT_FOUND (5) → No instance with ID '<id>' found. (matches v3).
• UNKNOWN (2) on a non‑terminal instance → looks up runtime status and throws Cannot <op> orchestration instance in the <State> state. (matches host wording).
• UNKNOWN (2) on a terminal instance → detail is not recoverable from the opaque error; the v4 status policy (200‑swallow vs 409/410, ideally a server‑side fix) is deferred to Functions v4 client: terminal/invalid-state control-plane ops surface opaque 2 UNKNOWN (HTTP 400) instead of a meaningful status #315, so those 3 specs are skipped.

Activity/entity failure text now surfaces the v4‑core shape (TaskFailedError: Activity task #N failed: …, EntityOperationFailedException: …) rather than v3's Activity function '<name>' failed:. The core error does not carry the function name, and reconstructing the exact v3 string would require a replay‑risky change in the shared core, so the E2E expectations were aligned to the v4‑native shape. (Name‑in‑error is a possible future core enhancement benefiting all SDKs.)

Cross‑language note

The 4 MiB gRPC cap is an extension‑defined default (.NET DurableTaskOptions.MaxGrpcMessageSizeInBytes = 4194304), sent to and honored consistently by every SDK worker. Raising it via maxGrpcMessageSizeInBytes in host.json is the same knob .NET‑isolated and Python use — no SDK‑side divergence.

Follow‑ups

• Functions v4 client: terminal/invalid-state control-plane ops surface opaque 2 UNKNOWN (HTTP 400) instead of a meaningful status #315 — terminal/invalid‑state control‑plane ops return an opaque 2 UNKNOWN; decide the v4 status policy (server‑side gRPC status‑detail fix preferred). 3 E2E specs skipped pending this.
• (Optional) decouple the JS client's send vs receive gRPC caps for exact .NET‑isolated parity.

Testing

• Compat unit: 91/91 (npm run test:unit -w durable-functions).
• Core: functions-grpc-support.spec.ts green.
• Functions host E2E: 32 passed / 0 failed / 13 skipped (Preview bundle + Azurite).
• npm run build -w durable-functions clean (core + compat).

[Copilot]

Pull request overview

Adds a minimal “single work-item” execution surface to the Durable Task JS worker so host integrations (e.g., Azure Functions) can execute one orchestrator/entity batch request per invocation without running the long-lived gRPC streaming loop. This aligns with the SDK’s role as a low-level Durable Task Scheduler (sidecar) client/worker implementation.

Changes:

• Added byte-level helper methods on TaskHubGrpcWorker to process serialized OrchestratorRequest / EntityBatchRequest payloads and return serialized responses.
• Introduced an in-process CapturingSidecarStub that captures completion payloads instead of sending them over gRPC.
• Added end-to-end tests and README documentation for the new host-integration surface.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
README.md	Documents the new low-level host integration APIs and clarifies the non–Durable Functions programming model scope.
packages/durabletask-js/test/functions-grpc-support.spec.ts	Adds e2e-style tests covering the new byte processors for orchestrations and entities.
packages/durabletask-js/src/worker/task-hub-grpc-worker.ts	Implements the new public byte-processing methods and the capturing sidecar stub.

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file

Comments suppressed due to low confidence (2)

packages/azure-functions-durable/src/client.ts:540

• When createHttpManagementPayload(instanceId) is used (no request), getInstanceStatusUrl falls back to baseUrl, but baseUrl defaults to an empty string. That yields relative URLs like /instances/<id> (and then /instances/<id>/terminate?...), which is likely unusable for callers and silently wrong. Consider throwing a clear error when baseUrl is missing and the request-less call style is used.

  // No request (classic Durable Functions v3 single-argument call): fall back to the base URL
  // supplied in the client binding configuration.
  const trimmedBaseUrl = baseUrl.replace(/\/+$/, "");
  return `${trimmedBaseUrl}/instances/${encodedInstanceId}`;
}

test/e2e-functions/test-app/package.json:5

• The comment_durable-functions text says the compat package pins core to a published version that predates the Functions worker helpers, but durable-functions depends on @microsoft/durabletask-js: 0.4.0 (the same version that introduces those helpers in this PR). The override is still useful for ensuring the test-app uses the in-repo core build, but the rationale here reads inaccurate and may confuse future maintainers.

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file

Comments suppressed due to low confidence (1)

packages/azure-functions-durable/src/get-client.ts:23

• getClient assumes context.options.extraInputs is always present. If it is undefined (e.g., a function that didn't register any extra inputs), this will throw a TypeError before you can surface the intended friendly error message.

export function getClient(context: InvocationContext): DurableFunctionsClient {
  const clientInput = context.options.extraInputs.find(isDurableClientInput);
  if (!clientInput) {

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file

[Copilot]

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• test/e2e-functions/test-app/package-lock.json: Generated file