Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

4.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Process-local coordination for operations that depend on stable URI scopes."""

import asyncio
import threading
from concurrent.futures import Future
from contextlib import asynccontextmanager
from dataclasses import dataclass
from typing import AsyncIterator, Optional, Sequence


def _normalize_uri(uri: str) -> str:
    return uri.rstrip("/")


def _normalize_uris(uris: Sequence[Optional[str]]) -> tuple[str, ...]:
    return tuple(sorted({_normalize_uri(uri) for uri in uris if uri}))


def uri_matches_prefix(uri: Optional[str], prefix: str) -> bool:
    """Return whether *uri* is equal to or below *prefix* on a path boundary."""
    if not uri:
        return False
    normalized_uri = _normalize_uri(uri)
    normalized_prefix = _normalize_uri(prefix)
    return normalized_uri == normalized_prefix or normalized_uri.startswith(f"{normalized_prefix}/")


def _uris_overlap(left: tuple[str, ...], right: tuple[str, ...]) -> bool:
    return any(
        uri_matches_prefix(left_uri, right_uri) or uri_matches_prefix(right_uri, left_uri)
        for left_uri in left
        for right_uri in right
    )


@dataclass(eq=False, frozen=True)
class _UriLease:
    account_id: str
    uris: tuple[str, ...]

    def overlaps(self, other: "_UriLease") -> bool:
        return self.account_id == other.account_id and _uris_overlap(self.uris, other.uris)


class UriMutationCoordinator:
    """Coordinate stable URI access and URI mutations within one process."""

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._waiters: set[Future[None]] = set()
        self._active_accesses: list[_UriLease] = []
        self._active_mutations: list[_UriLease] = []

    @asynccontextmanager
    async def access(
        self,
        account_id: str,
        uris: Sequence[Optional[str]],
    ) -> AsyncIterator[None]:
        """Hold a lease requiring the supplied URI scopes to remain stable."""
        lease = _UriLease(account_id=account_id, uris=_normalize_uris(uris))
        await self._acquire(lease, mutation=False)
        try:
            yield
        finally:
            await self._release(lease, mutation=False)

    @asynccontextmanager
    async def mutation(
        self,
        account_id: str,
        uris: Sequence[Optional[str]],
    ) -> AsyncIterator[None]:
        """Hold an exclusive lease for mutating the supplied URI scopes."""
        lease = _UriLease(account_id=account_id, uris=_normalize_uris(uris))
        await self._acquire(lease, mutation=True)
        try:
            yield
        finally:
            await self._release(lease, mutation=True)

    async def _acquire(self, lease: _UriLease, *, mutation: bool) -> None:
        while True:
            with self._lock:
                if not self._has_blocker(lease, mutation=mutation):
                    self._active_leases(mutation=mutation).append(lease)
                    return
                waiter: Future[None] = Future()
                self._waiters.add(waiter)
            try:
                await asyncio.wrap_future(waiter)
            finally:
                with self._lock:
                    self._waiters.discard(waiter)

    async def _release(self, lease: _UriLease, *, mutation: bool) -> None:
        with self._lock:
            active = self._active_leases(mutation=mutation)
            for index, current in enumerate(active):
                if current is lease:
                    del active[index]
                    break
            waiters = self._waiters
            self._waiters = set()
        for waiter in waiters:
            if waiter.set_running_or_notify_cancel():
                waiter.set_result(None)

    def _has_blocker(self, lease: _UriLease, *, mutation: bool) -> bool:
        if any(lease.overlaps(active) for active in self._active_mutations):
            return True
        return mutation and any(lease.overlaps(active) for active in self._active_accesses)

    def _active_leases(self, *, mutation: bool) -> list[_UriLease]:
        return self._active_mutations if mutation else self._active_accesses