feat(durable-functions): restore worker-side callHttp (#318)

[YunchuWang]

What & why

Restores the classic durable-functions v3 context.df.callHttp API on the v4 gRPC-based provider (packages/azure-functions-durable), which currently throws. Fixes #318.

The durabletask gRPC engine has no native durable-HTTP action, so the feature is rebuilt from core primitives. This ports Andy Staples' design from the sibling durabletask-python#155 (JS counterpart of #282).

Ported design (mirrors Python builtin.py)

• Built-in HTTP activity (BuiltIn__HttpActivity): performs a single fetch request and returns { statusCode, headers, content }. Non-2xx/202 responses are captured, not thrown (global fetch only rejects on network errors). Includes an SSRF guard rejecting any non-http/https scheme, and acquires a Managed Identity bearer token when a tokenSource is supplied.
• Built-in poll orchestrator (BuiltIn__HttpPollOrchestrator): a core-native async function* that calls the activity and, while the response is 202 Accepted with a Location header, waits on a replay-safe durable timer (fireAt = currentUtcDateTime + delay, never Date.now()) honoring Retry-After (delta-seconds and HTTP-date forms; 30s fallback, matching the classic host default), resolves a relative Location against the current URI, and re-polls. Honors the v3 enablePolling opt-out.
• callHttp(options): builds the request payload and schedules the poll orchestrator via callSubOrchestrator — a single yield, durable polling — returning Task<DurableHttpResponse>.
• Auto-registration: both builtins register exactly once when the package is imported, so existing apps work with no changes.

v3 API restored

Re-exports the v3 public shapes so v3 imports resolve unchanged: DurableHttpRequest, DurableHttpResponse, CallHttpOptions, ManagedIdentityTokenSource, TokenSource. callHttp accepts the v3 CallHttpOptions (method, url, body, headers, tokenSource, enablePolling, deprecated asynchronousPatternEnabled alias), JSON-stringifies an object body, and resolves enablePolling = enablePolling ?? asynchronousPatternEnabled ?? true.

Note: ManagedIdentityTokenSource.kind is "AzureManagedIdentity" to match the actual v3 source shape (the local azure-functions-durable-js clone), rather than "ManagedIdentity". Only resource is functionally significant.

⚠️ Trust-boundary change (v3 → v4)

In v3, the Functions host extension executed the HTTP request. In v4, it runs as a durable activity inside the app/worker process (via fetch). Therefore the egress network path, outbound identity, and firewall/VNet behavior follow the worker process, not the host — re-verify egress and any IP allow-lists. This is documented in the README migration section.

Managed identity (optional dependency)

Token acquisition uses @azure/identity DefaultAzureCredential, loaded via a lazy require only when a tokenSource is present (scope = resource.replace(/\/+$/,'') + '/.default'; sends the real Bearer <token>). It is added as an optional dependency; if a tokenSource is used without the package installed, a clear "install @azure/identity" error is thrown. Apps that don't use managed identity need no extra install.

Tests

• Built-in activity: 200 passthrough; missing uri throws; non-http/https scheme throws; tokenSource sets a real Authorization: Bearer <token> (credential mocked; asserts the real token); 202 captured (not thrown).
• Poll orchestrator: single 200 returns immediately (no timer); 202+Location yields activity → timer → re-poll; Retry-After delta-seconds and HTTP-date parsing; relative Location resolution; enablePolling=false returns the first 202 without looping.
• callHttp wiring: schedules the sub-orchestration under BUILTIN_HTTP_POLL_ORCHESTRATOR_NAME with the built payload; object body → JSON.stringify; default enablePolling true. Updated the existing orchestration-context.spec.ts test that previously asserted callHttp throws.
• Auto-registration: both builtins are registered via the app registration path.

Gates

• npm run build:core — exit 0
• npm run build -w durable-functions — exit 0
• npm run lint — exit 0
• durable-functions unit tests — 125 passed / 17 suites
• core unit tests — 1163 passed / 66 suites

Credit: ported from durabletask-python#155 (Andy Staples). CHANGELOG intentionally left unchanged.

Fixes #318

[Copilot]

Pull request overview

Restores the classic durable-functions v3 context.df.callHttp API for the durable-functions v4 Azure Functions compatibility package by rebuilding “durable HTTP” on top of durabletask gRPC core primitives (built-in activity + polling sub-orchestrator), including optional Managed Identity token acquisition and replay-safe 202 polling semantics.

Changes:

• Implemented built-in durable HTTP activity + polling orchestrator and wired DurableOrchestrationContext.callHttp() to schedule it via callSubOrchestrator.
• Added v3-compatible durable HTTP request/response/token models and re-exported them from the package entrypoint.
• Added unit tests for HTTP behavior, polling, and import-time auto-registration; updated README and added @azure/identity as an optional dependency.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/azure-functions-durable/src/http/builtin.ts	Adds built-in HTTP activity (fetch) and replay-safe 202 polling orchestrator; optional Managed Identity token acquisition.
packages/azure-functions-durable/src/http/models.ts	Introduces v3-compatible durable HTTP request/response/token models and internal payload shape.
packages/azure-functions-durable/src/orchestration-context.ts	Replaces the previous throwing callHttp implementation with sub-orchestrator scheduling and request payload building.
packages/azure-functions-durable/src/app.ts	Auto-registers the built-in HTTP orchestrator/activity on module import.
packages/azure-functions-durable/src/index.ts	Re-exports durable HTTP models to preserve v3 import compatibility.
packages/azure-functions-durable/test/unit/http-builtin.spec.ts	Adds unit tests for HTTP activity, token acquisition path, and polling/orchestrator behavior.
packages/azure-functions-durable/test/unit/http-builtin-registration.spec.ts	Adds tests asserting import-time auto-registration into the Functions app and shared worker registry.
packages/azure-functions-durable/test/unit/orchestration-context.spec.ts	Updates tests to assert callHttp scheduling behavior instead of throwing.
packages/azure-functions-durable/README.md	Updates migration notes to reflect restored callHttp and documents the trust-boundary change + optional identity dependency.
packages/azure-functions-durable/package.json	Adds @azure/identity as an optional dependency.
package-lock.json	Updates lockfile for optional dependency addition and workspace metadata.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

packages/azure-functions-durable/src/http/builtin.ts:98

• The require('@azure/identity') error handler catches all failures and always throws an "install @azure/identity" message. This will mask real runtime errors inside the dependency (or other require-time failures) and make diagnosing production issues harder. Only replace the error when the module is actually missing (MODULE_NOT_FOUND); otherwise rethrow the original error.

  try {
    identity = require("@azure/identity");
  } catch {
    throw new Error(
      "callHttp with a tokenSource requires the optional '@azure/identity' package. " +

packages/azure-functions-durable/src/http/builtin.ts:145

• Managed-identity token injection only checks headers["Authorization"], so a caller-supplied authorization (lowercase) header will be overwritten and/or duplicated. Since header names are case-insensitive, this can unexpectedly change the request's auth behavior.

  const headers: { [key: string]: string } = { ...(request.headers ?? {}) };
  const resource = request.tokenSource?.resource;
  if (resource) {
    const token = await acquireBearerToken(resource);
    if (headers["Authorization"] === undefined) {

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

packages/azure-functions-durable/src/http/builtin.ts:165

• The require("@azure/identity") error handling currently catches all failures and rethrows an "install @azure/identity" message. That can mask real load-time problems (e.g., ERR_REQUIRE_ESM, dependency initialization errors) when the package is present but fails to load.

  try {
    identity = require("@azure/identity");
  } catch {
    throw new Error(
      "callHttp with a tokenSource requires the optional '@azure/identity' package. " +

test/e2e-functions/test-app/src/functions/CallHttpOrchestration.ts:89

• location is built using ${u.protocol}//localhost:${u.port}/.... If request.url has no explicit port (default 80/443), u.port is an empty string and this produces an invalid URL like https://localhost:/api/HttpAuthEcho (extra colon).

    const u = new URL(request.url);
    const location = `${u.protocol}//localhost:${u.port}/api/HttpAuthEcho`;

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/azure-functions-durable/src/http/builtin.ts:238

• builtinHttpActivity currently relies on fetch’s default redirect behavior ("follow"). As noted in the comment, cross-origin redirects can forward custom headers (e.g., x-functions-key) to the redirect target, which is a credential-leak vector if the initial URI responds with an attacker-controlled redirect. Consider failing closed on cross-origin redirects (or using redirect:"manual" and explicitly re-applying the same-origin credential policy per hop), or document this as a deliberate security/compat tradeoff so users don’t assume the cross-origin stripping applies to redirects as well.

  // `redirect: "follow"` (the default): `fetch`/undici transparently follows 3xx redirects and, per the
  // Fetch Standard, drops `Authorization` (and `Cookie`) when a redirect crosses origins — but it does
  // NOT drop custom credential headers such as `x-functions-key`. Switching to `redirect: "manual"` and
  // re-applying our cross-origin policy per hop would close that residual gap, but it would change
  // observable single-request semantics (hop count, effective URL, cookie handling) in ways the

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

packages/azure-functions-durable/src/http/builtin.ts:165

• The lazy require('@azure/identity') catch block will also treat any load-time failure (e.g., syntax error, transitive dependency issue) as “package missing”, which can mask real runtime problems and make troubleshooting much harder. It’s safer to only translate MODULE_NOT_FOUND into the install hint and rethrow other errors.

  try {
    identity = require("@azure/identity");
  } catch {
    throw new Error(
      "callHttp with a tokenSource requires the optional '@azure/identity' package. " +

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

test/e2e-functions/test-app/src/functions/CallHttpOrchestration.ts:148

• u.port is an empty string when the incoming request is on the scheme default port (80/443). In that case this template literal produces an invalid URL like https://localhost:/api/HttpCrossOriginStart, which will make the e2e starter fail outside the local dev port=7071 scenario. Build the URL via URL mutation (or conditionally include the :${port} segment) to avoid emitting a trailing colon when the port is empty.

            url: `${u.protocol}//${firstHost}:${u.port}/api/HttpCrossOriginStart`,

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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

[andystaples]

Requesting changes for two blocking issues and two compatibility gaps. The core replay, polling, managed-identity, and continue-as-new changes look sound; the inline comments identify the remaining issues that prevent calling the feature fully secure and v3-equivalent.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

packages/azure-functions-durable/src/http/models.ts:37

• ManagedIdentityTokenSource.kind is currently a required property (because it’s declared as readonly kind: string), which makes TokenSource structurally require kind. However, the internal wire shape already treats kind as optional (DurableHttpRequestPayload.tokenSource.kind?: string), and the activity only uses resource. Making kind optional here improves v3-compatibility (callers can pass { resource: ... } without having to construct the class or add a kind field) while preserving current runtime behavior.

export class ManagedIdentityTokenSource {
  /** @hidden Discriminator matching the classic durable-functions v3 token-source shape. */
  readonly kind: string = "AzureManagedIdentity";

requesting review again