⚙️ FEATURE: Implement Server provider for remote API communication

[FernandoCelmer]

Summary

Implement a new Server ABC provider to replace the current Api provider, enabling full bidirectional communication between the dotflow library and a remote API server (e.g., dotflow-api).

Motivation

The current Api ABC and its ApiDefault implementation are limited:

• create_workflow works (best-effort HTTP POST)
• update_workflow is a no-op
• create_task is a no-op
• update_task is a no-op

The dotflow library needs a proper provider to send real-time execution data (workflow status, task status, errors, duration, context) to a remote server like dotflow-api.

Proposed Design

ABC: Server

class Server(ABC):

    @abstractmethod
    def create_workflow(self, workflow: Any) -> None:
        """Register a new workflow on the remote server."""

    @abstractmethod
    def update_workflow(self, workflow: Any) -> None:
        """Update workflow status (in_progress, completed, failed)."""

    @abstractmethod
    def create_task(self, task: Any) -> None:
        """Register a new task under a workflow."""

    @abstractmethod
    def update_task(self, task: Any) -> None:
        """Update task status, duration, context, errors, retry_count."""

Provider: ServerDefault

Default HTTP implementation that communicates with dotflow-api:

• Auth via X-User-Token header
• Config via env vars: DOTFLOW_SERVER_URL, DOTFLOW_USER_TOKEN
• Endpoints used:
  • POST /workflows — create workflow
  • PATCH /workflows/{id} — update workflow status
  • POST /workflows/{id}/tasks — create task
  • PATCH /tasks/{id} — update task (status, duration, errors, context)

Integration with Config

from dotflow import DotFlow, Config
from dotflow.providers import ServerDefault

config = Config(
    server=ServerDefault(
        base_url="https://api.example.com/api/v1",
        user_token="your-api-token",
    )
)

workflow = DotFlow(config=config)

Or via environment variables:

export DOTFLOW_SERVER_URL=https://api.example.com/api/v1
export DOTFLOW_USER_TOKEN=your-api-token

Task data sent on update

{
  "status": "Completed",
  "duration": 1.23,
  "retry_count": 0,
  "errors": [],
  "initial_context": {},
  "current_context": {"result": "data"},
  "previous_context": {}
}

Tasks

• Create Server ABC in dotflow/abc/server.py
• Create ServerDefault provider in dotflow/providers/server_default.py
• Add server parameter to Config
• Hook into TaskEngine lifecycle (start, complete, fail, retry)
• Hook into Manager lifecycle (workflow start, complete, fail)
• Add env var support (DOTFLOW_SERVER_URL, DOTFLOW_USER_TOKEN)
• Deprecate current Api ABC in favor of Server
• Add tests
• Add documentation