refactor: quota v3 integration (#35436)

Co-authored-by: Yansong Zhang <916125788@qq.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

api/services/app_generate_service.py

@@ -18,12 +18,13 @@ from core.app.features.rate_limiting import RateLimit
 from core.app.features.rate_limiting.rate_limit import rate_limit_context
 from core.app.layers.pause_state_persist_layer import PauseStateLayerConfig
 from core.db import session_factory
-from enums.quota_type import QuotaType, unlimited
+from enums.quota_type import QuotaType
 from extensions.otel import AppGenerateHandler, trace_span
 from models.model import Account, App, AppMode, EndUser
 from models.workflow import Workflow, WorkflowRun
 from services.errors.app import QuotaExceededError, WorkflowIdFormatError, WorkflowNotFoundError
 from services.errors.llm import InvokeRateLimitError
+from services.quota_service import QuotaService, unlimited
 from services.workflow_service import WorkflowService
 from tasks.app_generate.workflow_execute_task import AppExecutionParams, workflow_based_app_execution_task
 
@@ -106,7 +107,7 @@ class AppGenerateService:
         quota_charge = unlimited()
         if dify_config.BILLING_ENABLED:
             try:
-                quota_charge = QuotaType.WORKFLOW.consume(app_model.tenant_id)
+                quota_charge = QuotaService.reserve(QuotaType.WORKFLOW, app_model.tenant_id)
             except QuotaExceededError:
                 raise InvokeRateLimitError(f"Workflow execution quota limit reached for tenant {app_model.tenant_id}")
 
@@ -116,6 +117,7 @@ class AppGenerateService:
         request_id = RateLimit.gen_request_key()
         try:
             request_id = rate_limit.enter(request_id)
+            quota_charge.commit()
             effective_mode = (
                 AppMode.AGENT_CHAT if app_model.is_agent and app_model.mode != AppMode.AGENT_CHAT else app_model.mode
             )

api/services/async_workflow_service.py

@@ -22,6 +22,7 @@ from models.trigger import WorkflowTriggerLog, WorkflowTriggerLogDict
 from models.workflow import Workflow
 from repositories.sqlalchemy_workflow_trigger_log_repository import SQLAlchemyWorkflowTriggerLogRepository
 from services.errors.app import QuotaExceededError, WorkflowNotFoundError, WorkflowQuotaLimitError
+from services.quota_service import QuotaService, unlimited
 from services.workflow.entities import AsyncTriggerResponse, TriggerData, WorkflowTaskData
 from services.workflow.queue_dispatcher import QueueDispatcherManager, QueuePriority
 from services.workflow_service import WorkflowService
@@ -88,7 +89,10 @@ class AsyncWorkflowService:
             raise WorkflowNotFoundError(f"App not found: {trigger_data.app_id}")
 
         # 2. Get workflow
-        workflow = cls._get_workflow(workflow_service, app_model, trigger_data.workflow_id)
+        workflow = cls._get_workflow(workflow_service, app_model, trigger_data.workflow_id, session=session)
+
+        # commit read only session before starting the billig rpc call
+        session.commit()
 
         # 3. Get dispatcher based on tenant subscription
         dispatcher = dispatcher_manager.get_dispatcher(trigger_data.tenant_id)
@@ -131,9 +135,10 @@ class AsyncWorkflowService:
         trigger_log = trigger_log_repo.create(trigger_log)
         session.commit()
 
-        # 7. Check and consume quota
+        # 7. Reserve quota (commit after successful dispatch)
+        quota_charge = unlimited()
         try:
-            QuotaType.WORKFLOW.consume(trigger_data.tenant_id)
+            quota_charge = QuotaService.reserve(QuotaType.WORKFLOW, trigger_data.tenant_id)
         except QuotaExceededError as e:
             # Update trigger log status
             trigger_log.status = WorkflowTriggerStatus.RATE_LIMITED
@@ -153,13 +158,18 @@ class AsyncWorkflowService:
         # 9. Dispatch to appropriate queue
         task_data_dict = task_data.model_dump(mode="json")
 
-        task: AsyncResult[Any] | None = None
-        if queue_name == QueuePriority.PROFESSIONAL:
-            task = execute_workflow_professional.delay(task_data_dict)
-        elif queue_name == QueuePriority.TEAM:
-            task = execute_workflow_team.delay(task_data_dict)
-        else:  # SANDBOX
-            task = execute_workflow_sandbox.delay(task_data_dict)
+        try:
+            task: AsyncResult[Any] | None = None
+            if queue_name == QueuePriority.PROFESSIONAL:
+                task = execute_workflow_professional.delay(task_data_dict)
+            elif queue_name == QueuePriority.TEAM:
+                task = execute_workflow_team.delay(task_data_dict)
+            else:  # SANDBOX
+                task = execute_workflow_sandbox.delay(task_data_dict)
+            quota_charge.commit()
+        except Exception:
+            quota_charge.refund()
+            raise
 
         # 10. Update trigger log with task info
         trigger_log.status = WorkflowTriggerStatus.QUEUED
@@ -295,13 +305,21 @@ class AsyncWorkflowService:
             return [log.to_dict() for log in logs]
 
     @staticmethod
-    def _get_workflow(workflow_service: WorkflowService, app_model: App, workflow_id: str | None = None) -> Workflow:
+    def _get_workflow(
+        workflow_service: WorkflowService,
+        app_model: App,
+        workflow_id: str | None = None,
+        session: Session | None = None,
+    ) -> Workflow:
         """
         Get workflow for the app
 
         Args:
             app_model: App model instance
             workflow_id: Optional specific workflow ID
+            session: Reuse this SQLAlchemy session for the lookup when provided,
+                so the caller's explicit session bears the connection cost
+                instead of Flask's request-scoped ``db.session``.
 
         Returns:
             Workflow instance
@@ -311,12 +329,12 @@ class AsyncWorkflowService:
         """
         if workflow_id:
             # Get specific published workflow
-            workflow = workflow_service.get_published_workflow_by_id(app_model, workflow_id)
+            workflow = workflow_service.get_published_workflow_by_id(app_model, workflow_id, session=session)
             if not workflow:
                 raise WorkflowNotFoundError(f"Published workflow not found: {workflow_id}")
         else:
             # Get default published workflow
-            workflow = workflow_service.get_published_workflow(app_model)
+            workflow = workflow_service.get_published_workflow(app_model, session=session)
             if not workflow:
                 raise WorkflowNotFoundError(f"No published workflow found for app: {app_model.id}")
 

api/services/billing_service.py

@@ -32,6 +32,50 @@ class SubscriptionPlan(TypedDict):
     expiration_date: int
 
 
+class QuotaReserveResult(TypedDict):
+    reservation_id: str
+    available: int
+    reserved: int
+
+
+class QuotaCommitResult(TypedDict):
+    available: int
+    reserved: int
+    refunded: int
+
+
+class QuotaReleaseResult(TypedDict):
+    available: int
+    reserved: int
+    released: int
+
+
+_quota_reserve_adapter = TypeAdapter(QuotaReserveResult)
+_quota_commit_adapter = TypeAdapter(QuotaCommitResult)
+_quota_release_adapter = TypeAdapter(QuotaReleaseResult)
+
+
+class _TenantFeatureQuota(TypedDict):
+    usage: int
+    limit: int
+    reset_date: NotRequired[int]
+
+
+class TenantFeatureQuotaInfo(TypedDict):
+    """Response of /quota/info.
+
+    NOTE (hj24):
+    - Same convention as BillingInfo: billing may return int fields as str,
+      always keep non-strict mode to auto-coerce.
+    """
+
+    trigger_event: _TenantFeatureQuota
+    api_rate_limit: _TenantFeatureQuota
+
+
+_tenant_feature_quota_info_adapter = TypeAdapter(TenantFeatureQuotaInfo)
+
+
 class _BillingQuota(TypedDict):
     size: int
     limit: int
@@ -149,11 +193,63 @@ class BillingService:
 
     @classmethod
     def get_tenant_feature_plan_usage_info(cls, tenant_id: str):
+        """Deprecated: Use get_quota_info instead."""
         params = {"tenant_id": tenant_id}
-
         usage_info = cls._send_request("GET", "/tenant-feature-usage/info", params=params)
         return usage_info
 
+    @classmethod
+    def get_quota_info(cls, tenant_id: str) -> TenantFeatureQuotaInfo:
+        params = {"tenant_id": tenant_id}
+        return _tenant_feature_quota_info_adapter.validate_python(
+            cls._send_request("GET", "/quota/info", params=params)
+        )
+
+    @classmethod
+    def quota_reserve(
+        cls, tenant_id: str, feature_key: str, request_id: str, amount: int = 1, meta: dict | None = None
+    ) -> QuotaReserveResult:
+        """Reserve quota before task execution."""
+        payload: dict = {
+            "tenant_id": tenant_id,
+            "feature_key": feature_key,
+            "request_id": request_id,
+            "amount": amount,
+        }
+        if meta:
+            payload["meta"] = meta
+        return _quota_reserve_adapter.validate_python(cls._send_request("POST", "/quota/reserve", json=payload))
+
+    @classmethod
+    def quota_commit(
+        cls, tenant_id: str, feature_key: str, reservation_id: str, actual_amount: int, meta: dict | None = None
+    ) -> QuotaCommitResult:
+        """Commit a reservation with actual consumption."""
+        payload: dict = {
+            "tenant_id": tenant_id,
+            "feature_key": feature_key,
+            "reservation_id": reservation_id,
+            "actual_amount": actual_amount,
+        }
+        if meta:
+            payload["meta"] = meta
+        return _quota_commit_adapter.validate_python(cls._send_request("POST", "/quota/commit", json=payload))
+
+    @classmethod
+    def quota_release(cls, tenant_id: str, feature_key: str, reservation_id: str) -> QuotaReleaseResult:
+        """Release a reservation (cancel, return frozen quota)."""
+        return _quota_release_adapter.validate_python(
+            cls._send_request(
+                "POST",
+                "/quota/release",
+                json={
+                    "tenant_id": tenant_id,
+                    "feature_key": feature_key,
+                    "reservation_id": reservation_id,
+                },
+            )
+        )
+
     @classmethod
     def get_knowledge_rate_limit(cls, tenant_id: str) -> KnowledgeRateLimitDict:
         params = {"tenant_id": tenant_id}

api/services/feature_service.py

@@ -290,7 +290,7 @@ class FeatureService:
     def _fulfill_params_from_billing_api(cls, features: FeatureModel, tenant_id: str):
         billing_info = BillingService.get_info(tenant_id)
 
-        features_usage_info = BillingService.get_tenant_feature_plan_usage_info(tenant_id)
+        features_usage_info = BillingService.get_quota_info(tenant_id)
 
         features.billing.enabled = billing_info["enabled"]
         features.billing.subscription.plan = billing_info["subscription"]["plan"]

api/services/quota_service.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from configs import dify_config
+
+if TYPE_CHECKING:
+    from enums.quota_type import QuotaType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class QuotaCharge:
+    """
+    Result of a quota reservation (Reserve phase).
+
+    Lifecycle:
+        charge = QuotaService.consume(QuotaType.TRIGGER, tenant_id)
+        try:
+            do_work()
+            charge.commit()   # Confirm consumption
+        except:
+            charge.refund()   # Release frozen quota
+
+    If neither commit() nor refund() is called, the billing system's
+    cleanup CronJob will auto-release the reservation within ~75 seconds.
+    """
+
+    success: bool
+    charge_id: str | None  # reservation_id
+    _quota_type: QuotaType
+    _tenant_id: str | None = None
+    _feature_key: str | None = None
+    _amount: int = 0
+    _committed: bool = field(default=False, repr=False)
+
+    def commit(self, actual_amount: int | None = None) -> None:
+        """
+        Confirm the consumption with actual amount.
+
+        Args:
+            actual_amount: Actual amount consumed. Defaults to the reserved amount.
+                           If less than reserved, the difference is refunded automatically.
+        """
+        if self._committed or not self.charge_id or not self._tenant_id or not self._feature_key:
+            return
+
+        try:
+            from services.billing_service import BillingService
+
+            amount = actual_amount if actual_amount is not None else self._amount
+            BillingService.quota_commit(
+                tenant_id=self._tenant_id,
+                feature_key=self._feature_key,
+                reservation_id=self.charge_id,
+                actual_amount=amount,
+            )
+            self._committed = True
+            logger.debug(
+                "Committed %s quota for tenant %s, reservation_id: %s, amount: %d",
+                self._quota_type,
+                self._tenant_id,
+                self.charge_id,
+                amount,
+            )
+        except Exception:
+            logger.exception("Failed to commit quota, reservation_id: %s", self.charge_id)
+
+    def refund(self) -> None:
+        """
+        Release the reserved quota (cancel the charge).
+
+        Safe to call even if:
+        - charge failed or was disabled (charge_id is None)
+        - already committed (Release after Commit is a no-op)
+        - already refunded (idempotent)
+
+        This method guarantees no exceptions will be raised.
+        """
+        if not self.charge_id or not self._tenant_id or not self._feature_key:
+            return
+
+        QuotaService.release(self._quota_type, self.charge_id, self._tenant_id, self._feature_key)
+
+
+def unlimited() -> QuotaCharge:
+    from enums.quota_type import QuotaType
+
+    return QuotaCharge(success=True, charge_id=None, _quota_type=QuotaType.UNLIMITED)
+
+
+class QuotaService:
+    """Orchestrates quota reserve / commit / release lifecycle via BillingService."""
+
+    @staticmethod
+    def consume(quota_type: QuotaType, tenant_id: str, amount: int = 1) -> QuotaCharge:
+        """
+        Reserve + immediate Commit (one-shot mode).
+
+        The returned QuotaCharge supports .refund() which calls Release.
+        For two-phase usage (e.g. streaming), use reserve() directly.
+        """
+        charge = QuotaService.reserve(quota_type, tenant_id, amount)
+        if charge.success and charge.charge_id:
+            charge.commit()
+        return charge
+
+    @staticmethod
+    def reserve(quota_type: QuotaType, tenant_id: str, amount: int = 1) -> QuotaCharge:
+        """
+        Reserve quota before task execution (Reserve phase only).
+
+        The caller MUST call charge.commit() after the task succeeds,
+        or charge.refund() if the task fails.
+
+        Raises:
+            QuotaExceededError: When quota is insufficient
+        """
+        from services.billing_service import BillingService
+        from services.errors.app import QuotaExceededError
+
+        if not dify_config.BILLING_ENABLED:
+            logger.debug("Billing disabled, allowing request for %s", tenant_id)
+            return QuotaCharge(success=True, charge_id=None, _quota_type=quota_type)
+
+        logger.info("Reserving %d %s quota for tenant %s", amount, quota_type.value, tenant_id)
+
+        if amount <= 0:
+            raise ValueError("Amount to reserve must be greater than 0")
+
+        request_id = str(uuid.uuid4())
+        feature_key = quota_type.billing_key
+
+        try:
+            reserve_resp = BillingService.quota_reserve(
+                tenant_id=tenant_id,
+                feature_key=feature_key,
+                request_id=request_id,
+                amount=amount,
+            )
+
+            reservation_id = reserve_resp.get("reservation_id")
+            if not reservation_id:
+                logger.warning(
+                    "Reserve returned no reservation_id for %s, feature %s, response: %s",
+                    tenant_id,
+                    quota_type.value,
+                    reserve_resp,
+                )
+                raise QuotaExceededError(feature=quota_type.value, tenant_id=tenant_id, required=amount)
+
+            logger.debug(
+                "Reserved %d %s quota for tenant %s, reservation_id: %s",
+                amount,
+                quota_type.value,
+                tenant_id,
+                reservation_id,
+            )
+            return QuotaCharge(
+                success=True,
+                charge_id=reservation_id,
+                _quota_type=quota_type,
+                _tenant_id=tenant_id,
+                _feature_key=feature_key,
+                _amount=amount,
+            )
+
+        except QuotaExceededError:
+            raise
+        except ValueError:
+            raise
+        except Exception:
+            logger.exception("Failed to reserve quota for %s, feature %s", tenant_id, quota_type.value)
+            return unlimited()
+
+    @staticmethod
+    def check(quota_type: QuotaType, tenant_id: str, amount: int = 1) -> bool:
+        if not dify_config.BILLING_ENABLED:
+            return True
+
+        if amount <= 0:
+            raise ValueError("Amount to check must be greater than 0")
+
+        try:
+            remaining = QuotaService.get_remaining(quota_type, tenant_id)
+            return remaining >= amount if remaining != -1 else True
+        except Exception:
+            logger.exception("Failed to check quota for %s, feature %s", tenant_id, quota_type.value)
+            return True
+
+    @staticmethod
+    def release(quota_type: QuotaType, reservation_id: str, tenant_id: str, feature_key: str) -> None:
+        """Release a reservation. Guarantees no exceptions."""
+        try:
+            from services.billing_service import BillingService
+
+            if not dify_config.BILLING_ENABLED:
+                return
+
+            if not reservation_id:
+                return
+
+            logger.info("Releasing %s quota, reservation_id: %s", quota_type.value, reservation_id)
+            BillingService.quota_release(
+                tenant_id=tenant_id,
+                feature_key=feature_key,
+                reservation_id=reservation_id,
+            )
+        except Exception:
+            logger.exception("Failed to release quota, reservation_id: %s", reservation_id)
+
+    @staticmethod
+    def get_remaining(quota_type: QuotaType, tenant_id: str) -> int:
+        from services.billing_service import BillingService
+
+        try:
+            usage_info = BillingService.get_quota_info(tenant_id)
+            if isinstance(usage_info, dict):
+                feature_info = usage_info.get(quota_type.billing_key, {})
+                if isinstance(feature_info, dict):
+                    limit = feature_info.get("limit", 0)
+                    usage = feature_info.get("usage", 0)
+                    if limit == -1:
+                        return -1
+                    return max(0, limit - usage)
+            return 0
+        except Exception:
+            logger.exception("Failed to get remaining quota for %s, feature %s", tenant_id, quota_type.value)
+            return -1

api/services/trigger/webhook_service.py

@@ -38,6 +38,7 @@ from models.workflow import Workflow
 from services.async_workflow_service import AsyncWorkflowService
 from services.end_user_service import EndUserService
 from services.errors.app import QuotaExceededError
+from services.quota_service import QuotaService
 from services.trigger.app_trigger_service import AppTriggerService
 from services.workflow.entities import WebhookTriggerData
 
@@ -798,45 +799,47 @@ class WebhookService:
             Exception: If workflow execution fails
         """
         try:
-            with Session(db.engine) as session:
-                # Prepare inputs for the webhook node
-                # The webhook node expects webhook_data in the inputs
-                workflow_inputs = cls.build_workflow_inputs(webhook_data)
+            workflow_inputs = cls.build_workflow_inputs(webhook_data)
 
-                # Create trigger data
-                trigger_data = WebhookTriggerData(
-                    app_id=webhook_trigger.app_id,
-                    workflow_id=workflow.id,
-                    root_node_id=webhook_trigger.node_id,  # Start from the webhook node
-                    inputs=workflow_inputs,
-                    tenant_id=webhook_trigger.tenant_id,
+            trigger_data = WebhookTriggerData(
+                app_id=webhook_trigger.app_id,
+                workflow_id=workflow.id,
+                root_node_id=webhook_trigger.node_id,
+                inputs=workflow_inputs,
+                tenant_id=webhook_trigger.tenant_id,
+            )
+
+            end_user = EndUserService.get_or_create_end_user_by_type(
+                type=InvokeFrom.TRIGGER,
+                tenant_id=webhook_trigger.tenant_id,
+                app_id=webhook_trigger.app_id,
+                user_id=None,
+            )
+
+            try:
+                quota_charge = QuotaService.reserve(QuotaType.TRIGGER, webhook_trigger.tenant_id)
+            except QuotaExceededError:
+                AppTriggerService.mark_tenant_triggers_rate_limited(webhook_trigger.tenant_id)
+                logger.info(
+                    "Tenant %s rate limited, skipping webhook trigger %s",
+                    webhook_trigger.tenant_id,
+                    webhook_trigger.webhook_id,
                 )
+                raise
 
-                end_user = EndUserService.get_or_create_end_user_by_type(
-                    type=InvokeFrom.TRIGGER,
-                    tenant_id=webhook_trigger.tenant_id,
-                    app_id=webhook_trigger.app_id,
-                    user_id=None,
-                )
-
-                # consume quota before triggering workflow execution
-                try:
-                    QuotaType.TRIGGER.consume(webhook_trigger.tenant_id)
-                except QuotaExceededError:
-                    AppTriggerService.mark_tenant_triggers_rate_limited(webhook_trigger.tenant_id)
-                    logger.info(
-                        "Tenant %s rate limited, skipping webhook trigger %s",
-                        webhook_trigger.tenant_id,
-                        webhook_trigger.webhook_id,
+            try:
+                # NOTE: don not use `with sessionmaker(bind=db.engine, expire_on_commit=False).begin()`
+                # trigger_workflow_async need to handle multipe session commits internally
+                with Session(db.engine, expire_on_commit=False) as session:
+                    AsyncWorkflowService.trigger_workflow_async(
+                        session,
+                        end_user,
+                        trigger_data,
                     )
-                    raise
-
-                # Trigger workflow execution asynchronously
-                AsyncWorkflowService.trigger_workflow_async(
-                    session,
-                    end_user,
-                    trigger_data,
-                )
+                quota_charge.commit()
+            except Exception:
+                quota_charge.refund()
+                raise
 
         except Exception:
             logger.exception("Failed to trigger workflow for webhook %s", webhook_trigger.webhook_id)

api/services/workflow_service.py

@@ -156,11 +156,18 @@ class WorkflowService:
         # return draft workflow
         return workflow
 
-    def get_published_workflow_by_id(self, app_model: App, workflow_id: str) -> Workflow | None:
+    def get_published_workflow_by_id(
+        self, app_model: App, workflow_id: str, session: Session | None = None
+    ) -> Workflow | None:
         """
         fetch published workflow by workflow_id
+
+        When ``session`` is provided, reuse it so callers that already hold a
+        Session avoid checking out an extra request-scoped ``db.session``
+        connection. Falls back to ``db.session`` for backward compatibility.
         """
-        workflow = db.session.scalar(
+        bind = session if session is not None else db.session
+        workflow = bind.scalar(
             select(Workflow)
             .where(
                 Workflow.tenant_id == app_model.tenant_id,
@@ -178,16 +185,20 @@ class WorkflowService:
             )
         return workflow
 
-    def get_published_workflow(self, app_model: App) -> Workflow | None:
+    def get_published_workflow(self, app_model: App, session: Session | None = None) -> Workflow | None:
         """
         Get published workflow
+
+        When ``session`` is provided, reuse it so callers that already hold a
+        Session avoid checking out an extra request-scoped ``db.session``
+        connection. Falls back to ``db.session`` for backward compatibility.
         """
 
         if not app_model.workflow_id:
             return None
 
-        # fetch published workflow by workflow_id
-        workflow = db.session.scalar(
+        bind = session if session is not None else db.session
+        workflow = bind.scalar(
             select(Workflow)
             .where(
                 Workflow.tenant_id == app_model.tenant_id,