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; 1s fallback), 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) {

[YunchuWang]

make this more succinct and customer facing