Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

16.1 KB
Raw Blame
"""Redis-backed run records, event streams, and private cancellation intents.

The store writes status-only run records as JSON strings and events as Redis
streams. HTTP event cursors are Redis stream ids; ``0-0`` means replay from the
beginning for polling and SSE. Records, event streams, and intents share one retention window
that is refreshed when status or event data is written. Execution is scheduled
in-process by ``dify_agent.runtime.run_scheduler``; Redis is not a job queue, and
create-run payloads are never persisted because layer config may include
sensitive runtime configuration.
"""

from collections.abc import AsyncIterator, Awaitable
from typing import cast, override

from redis.asyncio import Redis

from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.protocol.schemas import (
    AgentRunUsage,
    RUN_EVENT_ADAPTER,
    CancelRunRequest,
    RunCancelledEvent,
    RunCancelledEventData,
    RunEvent,
    RunEventsResponse,
    RunStatus,
    utc_now,
)
from dify_agent.runtime.cancellation import RunCancellationIntent
from dify_agent.runtime.event_sink import (
    NonTerminalRunEvent,
    RunEventSink,
    RunFinalizationResult,
    RunStreamSealedError,
    TerminalRunEvent,
    terminal_event_status_fields,
)
from dify_agent.server.schemas import RunRecord, new_run_id
from dify_agent.server.settings import DEFAULT_RUN_EVENT_STREAM_MAX_LENGTH, DEFAULT_RUN_RETENTION_SECONDS
from dify_agent.storage.redis_keys import run_cancel_intent_key, run_events_key, run_record_key

_TERMINAL_RUN_EVENT_TYPES = {"run_succeeded", "run_failed", "run_cancelled"}


class RunNotFoundError(LookupError):
    """Raised when a requested run record does not exist."""


_FINALIZE_RUN_SCRIPT = """
local record_json = redis.call("GET", KEYS[1])
if not record_json then
    return {-1, "", ""}
end

local record = cjson.decode(record_json)
if record.status ~= "running" then
    return {0, tostring(record.status), ""}
end

if redis.call("EXISTS", KEYS[3]) == 1 then
    return {-2, "running", ""}
end

record.status = ARGV[1]
record.updated_at = ARGV[2]
if ARGV[3] == "1" then
    record.error = ARGV[4]
else
    record.error = cjson.null
end
if ARGV[5] == "1" then
    record.error_type = ARGV[6]
else
    record.error_type = cjson.null
end

local ttl = tonumber(ARGV[8])
local updated_record_json = cjson.encode(record)
local event_id = redis.call("XADD", KEYS[2], "MAXLEN", "~", ARGV[9], "*", "payload", ARGV[7])
redis.call("EXPIRE", KEYS[2], ttl)
redis.call("SET", KEYS[1], updated_record_json, "EX", ttl)
return {1, ARGV[1], event_id}
"""


_APPEND_EVENT_SCRIPT = """
local record_json = redis.call("GET", KEYS[1])
if not record_json then
    return {-1, ""}
end

local record = cjson.decode(record_json)
if record.status ~= "running" then
    return {0, tostring(record.status), ""}
end

local ttl = tonumber(ARGV[3])
local event_id = redis.call("XADD", KEYS[2], "MAXLEN", "~", ARGV[2], "*", "payload", ARGV[1])
redis.call("EXPIRE", KEYS[2], ttl)
redis.call("EXPIRE", KEYS[1], ttl)
return {1, "running", event_id}
"""


_REQUEST_CANCELLATION_SCRIPT = """
local record_json = redis.call("GET", KEYS[1])
if not record_json then
    return {-1, ""}
end

local record = cjson.decode(record_json)
if record.status == "succeeded" or record.status == "failed" then
    return {0, tostring(record.status)}
end
if record.status == "cancelled" then
    return {1, "cancelled"}
end
if redis.call("EXISTS", KEYS[2]) == 1 then
    return {1, "running"}
end

local ttl = tonumber(ARGV[2])
redis.call("XADD", KEYS[2], "MAXLEN", "1", "*", "payload", ARGV[1])
redis.call("EXPIRE", KEYS[2], ttl)
redis.call("EXPIRE", KEYS[1], ttl)
redis.call("EXPIRE", KEYS[3], ttl)
return {1, "running"}
"""


_FINALIZE_CANCELLATION_SCRIPT = """
local record_json = redis.call("GET", KEYS[1])
if not record_json then
    return {-1, "", ""}
end

local record = cjson.decode(record_json)
if record.status == "cancelled" then
    return {0, "cancelled", ""}
end
if record.status ~= "running" then
    return {0, tostring(record.status), ""}
end
if redis.call("EXISTS", KEYS[2]) == 0 then
    return {-2, "running", ""}
end

record.status = "cancelled"
record.updated_at = ARGV[1]
if ARGV[2] == "1" then
    record.error = ARGV[3]
else
    record.error = cjson.null
end
record.error_type = cjson.null

local ttl = tonumber(ARGV[5])
local event_id = redis.call("XADD", KEYS[3], "MAXLEN", "~", ARGV[6], "*", "payload", ARGV[4])
redis.call("DEL", KEYS[2])
redis.call("EXPIRE", KEYS[3], ttl)
redis.call("SET", KEYS[1], cjson.encode(record), "EX", ttl)
return {1, "cancelled", event_id}
"""


class RedisRunStore(RunEventSink):
    """Async Redis implementation for run records and event logs.

    ``run_retention_seconds`` is applied to both the run record key and the
    per-run Redis stream. Every public stream write applies an approximate
    maximum length before refreshing both TTLs, so active runs cannot grow one
    Redis key without bound without paying the CPU cost of exact per-entry
    trimming. The transaction also ensures a newly created stream is not left
    without expiration if the client is interrupted between commands.
    Event writes refresh the record TTL so long-running runs that keep producing
    events do not lose their status record mid-run.
    """

    redis: Redis
    prefix: str
    run_retention_seconds: int
    run_event_stream_max_length: int

    def __init__(
        self,
        redis: Redis,
        *,
        prefix: str = "dify-agent",
        run_retention_seconds: int = DEFAULT_RUN_RETENTION_SECONDS,
        run_event_stream_max_length: int = DEFAULT_RUN_EVENT_STREAM_MAX_LENGTH,
    ) -> None:
        if run_retention_seconds <= 0:
            raise ValueError("run_retention_seconds must be positive")
        if run_event_stream_max_length <= 0:
            raise ValueError("run_event_stream_max_length must be positive")
        self.redis = redis
        self.prefix = prefix
        self.run_retention_seconds = run_retention_seconds
        self.run_event_stream_max_length = run_event_stream_max_length

    async def create_run(self) -> RunRecord:
        """Persist a running run record without storing the create request."""
        run_id = new_run_id()
        record = RunRecord(run_id=run_id, status="running")
        await self.redis.set(
            run_record_key(self.prefix, run_id),
            record.model_dump_json(),
            ex=self.run_retention_seconds,
        )
        return record

    async def get_run(self, run_id: str) -> RunRecord:
        """Return one run record or raise ``RunNotFoundError``."""
        value = await self.redis.get(run_record_key(self.prefix, run_id))
        if value is None:
            raise RunNotFoundError(run_id)
        if isinstance(value, bytes):
            value = value.decode()
        return RunRecord.model_validate_json(value)

    @override
    async def append_event(self, event: NonTerminalRunEvent) -> str:
        """Append a non-terminal event while the durable run status is still ``running``.

        The status check and the write share one linearization point with
        ``finalize_run``/``finalize_cancellation``: once a terminal transition
        wins, late non-terminal appends are rejected without consuming a
        cursor or refreshing retention.
        """
        payload = RUN_EVENT_ADAPTER.dump_json(event, exclude={"id"}).decode()
        evaluation = cast(
            Awaitable[object],
            self.redis.eval(
                _APPEND_EVENT_SCRIPT,
                2,
                run_record_key(self.prefix, event.run_id),
                run_events_key(self.prefix, event.run_id),
                payload,
                str(self.run_event_stream_max_length),
                str(self.run_retention_seconds),
            ),
        )
        result = cast(list[object], await evaluation)
        applied = int(cast(int | bytes | str, result[0]))
        if applied == -1:
            raise RunNotFoundError(event.run_id)
        if applied == 0:
            raise RunStreamSealedError(event.run_id, cast(RunStatus, _decode_redis_text(result[1])))
        return _decode_redis_text(result[2])

    @override
    async def finalize_run(self, event: TerminalRunEvent) -> RunFinalizationResult:
        """Atomically append the first success/failure event and update its run record."""
        status, error, error_type = terminal_event_status_fields(event)
        payload = RUN_EVENT_ADAPTER.dump_json(event, exclude={"id"}).decode()
        evaluation = cast(
            Awaitable[object],
            self.redis.eval(
                _FINALIZE_RUN_SCRIPT,
                3,
                run_record_key(self.prefix, event.run_id),
                run_events_key(self.prefix, event.run_id),
                run_cancel_intent_key(self.prefix, event.run_id),
                status,
                event.created_at.isoformat(),
                "1" if error is not None else "0",
                error or "",
                "1" if error_type is not None else "0",
                error_type.value if error_type is not None else "",
                payload,
                str(self.run_retention_seconds),
                str(self.run_event_stream_max_length),
            ),
        )
        raw_result = await evaluation
        result = cast(list[object], raw_result)
        applied = int(cast(int | bytes | str, result[0]))
        if applied == -1:
            raise RunNotFoundError(event.run_id)

        persisted_status = cast(RunStatus, _decode_redis_text(result[1]))
        event_id = _decode_redis_text(result[2]) or None
        return RunFinalizationResult(
            applied=applied == 1,
            status=persisted_status,
            event_id=event_id,
        )

    async def request_cancellation(self, run_id: str, request: CancelRunRequest) -> RunStatus:
        """Atomically persist the first cancellation intent for a running run."""
        intent = RunCancellationIntent(
            reason=request.reason,
            message=request.message,
            requested_at=utc_now(),
        )
        evaluation = cast(
            Awaitable[object],
            self.redis.eval(
                _REQUEST_CANCELLATION_SCRIPT,
                3,
                run_record_key(self.prefix, run_id),
                run_cancel_intent_key(self.prefix, run_id),
                run_events_key(self.prefix, run_id),
                intent.model_dump_json(),
                str(self.run_retention_seconds),
            ),
        )
        result = cast(list[object], await evaluation)
        if int(cast(int | bytes | str, result[0])) == -1:
            raise RunNotFoundError(run_id)
        return cast(RunStatus, _decode_redis_text(result[1]))

    async def get_cancellation_intent(self, run_id: str) -> RunCancellationIntent | None:
        """Return the accepted private cancellation intent, if one exists."""
        entries = await self.redis.xrange(run_cancel_intent_key(self.prefix, run_id), count=1)
        if not entries:
            return None
        return self._decode_cancellation_intent(entries[0][1])

    async def wait_for_cancellation(self, run_id: str) -> RunCancellationIntent:
        """Wait until the first accepted private cancellation intent is available."""
        response = await self.redis.xread(
            {run_cancel_intent_key(self.prefix, run_id): "0-0"},
            block=0,
            count=1,
        )
        return self._decode_cancellation_intent(response[0][1][0][1])

    async def finalize_cancellation(
        self,
        run_id: str,
        intent: RunCancellationIntent,
        *,
        session_snapshot: SessionSnapshot | None = None,
        usage: AgentRunUsage | None = None,
    ) -> RunFinalizationResult:
        """Atomically publish cancellation after the owner runner has exited."""
        event = RunCancelledEvent(
            run_id=run_id,
            data=RunCancelledEventData(
                reason=intent.reason,
                message=intent.message,
                session_snapshot=session_snapshot,
                usage=usage,
            ),
            created_at=utc_now(),
        )
        payload = RUN_EVENT_ADAPTER.dump_json(event, exclude={"id"}).decode()
        error = event.data.message or event.data.reason
        evaluation = cast(
            Awaitable[object],
            self.redis.eval(
                _FINALIZE_CANCELLATION_SCRIPT,
                3,
                run_record_key(self.prefix, run_id),
                run_cancel_intent_key(self.prefix, run_id),
                run_events_key(self.prefix, run_id),
                event.created_at.isoformat(),
                "1" if error is not None else "0",
                error or "",
                payload,
                str(self.run_retention_seconds),
                str(self.run_event_stream_max_length),
            ),
        )
        result = cast(list[object], await evaluation)
        applied = int(cast(int | bytes | str, result[0]))
        if applied == -1:
            raise RunNotFoundError(run_id)
        return RunFinalizationResult(
            applied=applied == 1,
            status=cast(RunStatus, _decode_redis_text(result[1])),
            event_id=_decode_redis_text(result[2]) or None,
        )

    async def get_events(self, run_id: str, *, after: str = "0-0", limit: int = 100) -> RunEventsResponse:
        """Read a nonblocking page strictly after ``after`` using Redis 6.0-compatible XREAD.

        An empty page preserves the supplied cursor; a missing run raises
        ``RunNotFoundError``.
        """
        await self.get_run(run_id)
        response = await self.redis.xread(
            {run_events_key(self.prefix, run_id): after},
            count=limit,
        )
        events = [
            self._decode_event(run_id, raw_id, fields)
            for _stream_name, entries in response
            for raw_id, fields in entries
        ]
        next_cursor = events[-1].id if events else after
        return RunEventsResponse(run_id=run_id, events=events, next_cursor=next_cursor)

    async def iter_events(self, run_id: str, *, after: str = "0-0") -> AsyncIterator[RunEvent]:
        """Yield replayed and future events through the first terminal event."""
        await self.get_run(run_id)
        cursor = after
        while True:
            page = await self.get_events(run_id, after=cursor, limit=100)
            for event in page.events:
                if event.id is not None:
                    cursor = event.id
                yield event
                if event.type in _TERMINAL_RUN_EVENT_TYPES:
                    return
            if not page.events:
                break
        while True:
            response = await self.redis.xread({run_events_key(self.prefix, run_id): cursor}, block=30_000, count=100)
            if not response:
                continue
            for _stream_name, entries in response:
                for raw_id, fields in entries:
                    event = self._decode_event(run_id, raw_id, fields)
                    if event.id is not None:
                        cursor = event.id
                    yield event
                    if event.type in _TERMINAL_RUN_EVENT_TYPES:
                        return

    @staticmethod
    def _decode_event(run_id: str, raw_id: object, fields: dict[object, object]) -> RunEvent:
        """Decode one Redis stream entry into a public event."""
        payload = fields.get(b"payload") or fields.get("payload")
        if isinstance(payload, bytes):
            payload = payload.decode()
        event_id = raw_id.decode() if isinstance(raw_id, bytes) else str(raw_id)
        event = RUN_EVENT_ADAPTER.validate_json(cast(str, payload))
        return event.model_copy(update={"id": event_id, "run_id": run_id})

    @staticmethod
    def _decode_cancellation_intent(fields: dict[object, object]) -> RunCancellationIntent:
        payload = fields.get(b"payload") or fields.get("payload")
        if isinstance(payload, bytes):
            payload = payload.decode()
        return RunCancellationIntent.model_validate_json(cast(str, payload))


def _decode_redis_text(value: object) -> str:
    return value.decode() if isinstance(value, bytes) else str(value)


__all__ = [
    "DEFAULT_RUN_EVENT_STREAM_MAX_LENGTH",
    "DEFAULT_RUN_RETENTION_SECONDS",
    "RedisRunStore",
    "RunNotFoundError",
]