[WORKFLOW SDK BUG] Workflow constructors reject Unix-domain socket DAPR_GRPC_ENDPOINT

[Cerebus]

Expected Behavior

WorkflowRuntime and DaprWorkflowClient should accept an absolute Unix-domain socket endpoint supplied through DAPR_GRPC_ENDPOINT, for example:

unix:///private/tmp/dapr-sockets/dapr-myapp-grpc.socket

GrpcEndpoint explicitly lists unix as an accepted scheme, so an absolute socket path should be accepted and converted to a gRPC-compatible Unix socket target.

This is needed when separate local applications each run their own Dapr sidecar. Unix-domain sockets avoid requiring every independently launched application to coordinate or search for a unique host TCP port.

Actual Behavior

Both Workflow SDK constructors fail immediately while parsing the endpoint, before making any network connection:

ValueError: paths are not supported for gRPC endpoints: '/private/tmp/dapr-sockets/dapr-myapp-grpc.socket'

The above exception was the direct cause of the following exception:

  dapr.clients.exceptions.DaprInternalError: paths are not supported for gRPC endpoints: '/private/tmp/dapr-sockets/dapr-myapp-grpc.socket'

The failure occurs because GrpcEndpoint accepts unix as a scheme but then rejects every parsed URI containing a path:

  class URIParseConfig:
      ACCEPTED_SCHEMES = [
          "dns",
          "unix",
          "unix-abstract",
          "vsock",
          "http",
          "https",
      ]

  def _validate_path_and_query(self) -> None:
      if self._parsed_url.path:
          raise ValueError(
              f"paths are not supported for gRPC endpoints: '{self._parsed_url.path}'"
          )

For an endpoint such as unix:///private/tmp/dapr.sock, the socket filename necessarily appears in parsed_url.path. The validation therefore makes the accepted unix scheme unusable with an absolute filesystem socket.

WorkflowRuntime and DaprWorkflowClient both pass the result of getAddress() through this parser:

  address = getAddress(host, port)

  try:
      uri = GrpcEndpoint(address)
  except ValueError as error:
      raise DaprInternalError(f"{error}") from error

Steps to Reproduce the Problem

Install the released packages:

pip install "dapr==1.18.3" "dapr-ext-workflow==1.18.3"

Run:

from dapr.conf import settings
from dapr.ext.workflow import WorkflowRuntime

settings.DAPR_GRPC_ENDPOINT = (
    "unix:///private/tmp/dapr-sockets/dapr-myapp-grpc.socket"
)

WorkflowRuntime()

Result:

Traceback (most recent call last):
  ...
  File ".../dapr/conf/helpers.py", line ..., in _validate_path_and_query
    raise ValueError(
  ValueError: paths are not supported for gRPC endpoints: '/private/tmp/dapr-sockets/dapr-myapp-grpc.socket'

  The above exception was the direct cause of the following exception:

  Traceback (most recent call last):
    ...
    File ".../dapr/ext/workflow/workflow_runtime.py", line ..., in __init__
      raise DaprInternalError(f'{error}') from error
  dapr.clients.exceptions.DaprInternalError: paths are not supported for gRPC endpoints: '/private/tmp/dapr-sockets/dapr-myapp-grpc.socket'

DaprWorkflowClient() fails through the same getAddress() and GrpcEndpoint path.

The Dapr runtime does not need to be running to reproduce this. Endpoint parsing fails before any network operation.

A smaller reproduction without the Workflow SDK is:

from dapr.conf.helpers import GrpcEndpoint

GrpcEndpoint(
    "unix:///private/tmp/dapr-sockets/dapr-myapp-grpc.socket"
)

Environment where reproduced:

• Python: 3.12.13
• dapr: 1.18.3
• dapr-ext-workflow: 1.18.3
• OS: macOS
• Dapr runtime installed locally: 1.18.4, although the runtime is not reached by this reproduction

A likely fix is to allow a parsed path when the endpoint scheme is unix, while retaining the existing path restriction for endpoint schemes where paths are invalid.

Regression coverage should include both GrpcEndpoint("unix:///tmp/dapr.sock") and construction of WorkflowRuntime and DaprWorkflowClient when DAPR_GRPC_ENDPOINT contains that endpoint.

Release Note

RELEASE NOTE: FIX Allow the Python Workflow SDK to use Unix-domain socket Dapr gRPC endpoints.