port-ocean 0.28.5__py3-none-any.whl → 0.29.0__py3-none-any.whl

port_ocean/core/event_listener/factory.py

@@ -13,6 +13,10 @@ from port_ocean.core.event_listener import (
     KafkaEventListenerSettings,
     PollingEventListenerSettings,
 )
+from port_ocean.core.event_listener.actions_only import (
+    ActionsOnlyEventListener,
+    ActionsOnlyEventListenerSettings,
+)
 from port_ocean.core.event_listener.base import (
     BaseEventListener,
     EventListenerEvents,
@@ -21,6 +25,7 @@ from port_ocean.core.event_listener.webhooks_only import (
     WebhooksOnlyEventListener,
     WebhooksOnlyEventListenerSettings,
 )
+from port_ocean.core.models import EventListenerType
 from port_ocean.exceptions.core import UnsupportedEventListenerTypeException
 
 
@@ -57,12 +62,11 @@ class EventListenerFactory:
         wrapped_events: EventListenerEvents = {"on_resync": self.events["on_resync"]}
         event_listener: BaseEventListener
         config = self.context.config.event_listener
-        _type = config.type.lower()
         assert_message = "Invalid event listener config, expected KafkaEventListenerSettings and got {0}"
-        logger.info(f"Found event listener type: {_type}")
+        logger.info(f"Found event listener type: {config.type}")
 
-        match _type:
-            case "kafka":
+        match config.type:
+            case EventListenerType.KAFKA:
                 assert isinstance(
                     config, KafkaEventListenerSettings
                 ), assert_message.format(type(config))
@@ -75,31 +79,36 @@ class EventListenerFactory:
                     self.context.config.integration.type,
                 )
 
-            case "webhook":
+            case EventListenerType.WEBHOOK:
                 assert isinstance(
                     config, HttpEventListenerSettings
                 ), assert_message.format(type(config))
                 event_listener = HttpEventListener(wrapped_events, config)
 
-            case "polling":
+            case EventListenerType.POLLING:
                 assert isinstance(
                     config, PollingEventListenerSettings
                 ), assert_message.format(type(config))
                 event_listener = PollingEventListener(wrapped_events, config)
 
-            case "once":
+            case EventListenerType.ONCE:
                 assert isinstance(
                     config, OnceEventListenerSettings
                 ), assert_message.format(type(config))
                 event_listener = OnceEventListener(wrapped_events, config)
-            case "webhooks_only":
+            case EventListenerType.WEBHOOKS_ONLY:
                 assert isinstance(
                     config, WebhooksOnlyEventListenerSettings
                 ), assert_message.format(type(config))
                 event_listener = WebhooksOnlyEventListener(wrapped_events, config)
+            case EventListenerType.ACTIONS_ONLY:
+                assert isinstance(
+                    config, ActionsOnlyEventListenerSettings
+                ), assert_message.format(type(config))
+                event_listener = ActionsOnlyEventListener(wrapped_events, config)
             case _:
                 raise UnsupportedEventListenerTypeException(
-                    f"Event listener {_type} not supported"
+                    f"Event listener {config.type} not supported"
                 )
 
         return event_listener

port_ocean/core/event_listener/http.py

@@ -1,4 +1,4 @@
-from typing import Literal, Any
+from typing import Any, Literal
 
 from fastapi import APIRouter
 from loguru import logger
@@ -11,6 +11,7 @@ from port_ocean.core.event_listener.base import (
     EventListenerEvents,
     EventListenerSettings,
 )
+from port_ocean.core.models import EventListenerType
 
 
 class HttpEventListenerSettings(EventListenerSettings):
@@ -19,12 +20,12 @@ class HttpEventListenerSettings(EventListenerSettings):
     The `HttpEventListenerSettings` specifically includes settings related to the HTTP event listener (Webhook).
 
     Attributes:
-        type (Literal["WEBHOOK"]): A literal indicating the type of the event listener, which is set to "WEBHOOK" for this class.
+        type (EventListenerType): A literal indicating the type of the event listener, which is set to "WEBHOOK" for this class.
         app_host (AnyHttpUrl): The base URL of the application hosting the webhook.
                                The "AnyHttpUrl" type indicates that the value must be a valid HTTP/HTTPS URL.
     """
 
-    type: Literal["WEBHOOK"]
+    type: Literal[EventListenerType.WEBHOOK]
     app_host: AnyHttpUrl = Field(..., sensitive=True)
 
     def get_changelog_destination_details(self) -> dict[str, Any]:

port_ocean/core/event_listener/kafka.py

@@ -17,6 +17,7 @@ from port_ocean.core.event_listener.base import (
     EventListenerSettings,
 )
 from pydantic import validator
+from port_ocean.core.models import EventListenerType
 
 
 class KafkaEventListenerSettings(EventListenerSettings):
@@ -25,7 +26,7 @@ class KafkaEventListenerSettings(EventListenerSettings):
     The `KafkaEventListenerSettings` specifically includes settings related to the Kafka event listener.
 
     Attributes:
-        type (Literal["KAFKA"]): A literal indicating the type of the event listener, which is set to "KAFKA" for this class.
+        type (EventListenerType): A literal indicating the type of the event listener, which is set to "KAFKA" for this class.
         brokers (str): The comma-separated list of Kafka broker URLs to connect to.
         security_protocol (str): The security protocol used for communication with Kafka brokers.
                                  The default value is "SASL_SSL".
@@ -38,7 +39,7 @@ class KafkaEventListenerSettings(EventListenerSettings):
                                      The default value is 1 second.
     """
 
-    type: Literal["KAFKA"]
+    type: Literal[EventListenerType.KAFKA]
     brokers: str = (
         "b-1-public.publicclusterprod.t9rw6w.c1.kafka.eu-west-1.amazonaws.com:9196,b-2-public.publicclusterprod.t9rw6w.c1.kafka.eu-west-1.amazonaws.com:9196,b-3-public.publicclusterprod.t9rw6w.c1.kafka.eu-west-1.amazonaws.com:9196"
     )

port_ocean/core/event_listener/once.py

@@ -1,6 +1,6 @@
 import datetime
 import signal
-from typing import Literal, Any
+from typing import Any, Literal
 
 from loguru import logger
 
@@ -9,6 +9,7 @@ from port_ocean.core.event_listener.base import (
     EventListenerEvents,
     EventListenerSettings,
 )
+from port_ocean.core.models import EventListenerType
 from port_ocean.utils.repeat import repeat_every
 from port_ocean.context.ocean import ocean
 from port_ocean.utils.time import convert_str_to_utc_datetime, convert_to_minutes
@@ -21,7 +22,9 @@ class OnceEventListenerSettings(EventListenerSettings):
     This class inherits from `EventListenerSettings`, which provides a foundation for creating event listener settings.
     """
 
-    type: Literal["ONCE"]
+    type: Literal[EventListenerType.ONCE]
+    should_process_webhooks: bool = False
+    should_run_actions: bool = False
 
 
 class OnceEventListener(BaseEventListener):

port_ocean/core/event_listener/polling.py

@@ -1,5 +1,5 @@
 from asyncio import Task, get_event_loop
-from typing import Literal, Any
+from typing import Any, Literal
 
 from loguru import logger
 
@@ -9,6 +9,7 @@ from port_ocean.core.event_listener.base import (
     EventListenerEvents,
     EventListenerSettings,
 )
+from port_ocean.core.models import EventListenerType
 from port_ocean.utils.repeat import repeat_every
 from port_ocean.utils.signal import signal_handler
 
@@ -16,14 +17,14 @@ from port_ocean.utils.signal import signal_handler
 class PollingEventListenerSettings(EventListenerSettings):
     """
     Attributes:
-        type (Literal["POLLING"]): A literal indicating the type of the event listener, which is set to "POLLING" for this class.
+        type (EventListenerType): A literal indicating the type of the event listener, which is set to "POLLING" for this class.
         resync_on_start (bool): A flag indicating whether to trigger a resync event on the start of the polling event listener.
                                 If True, the "on_resync" event will be triggered immediately when the polling listener starts.
         interval (int): The interval in seconds at which the polling event listener checks for changes in the integration.
                         The default interval is set to 60 seconds.
     """
 
-    type: Literal["POLLING"]
+    type: Literal[EventListenerType.POLLING]
     resync_on_start: bool = True
     interval: int = 60
 

port_ocean/core/event_listener/webhooks_only.py

@@ -1,5 +1,4 @@
 from typing import Literal
-
 from loguru import logger
 
 from port_ocean.core.event_listener.base import (
@@ -7,6 +6,7 @@ from port_ocean.core.event_listener.base import (
     EventListenerEvents,
     EventListenerSettings,
 )
+from port_ocean.core.models import EventListenerType
 
 
 class WebhooksOnlyEventListenerSettings(EventListenerSettings):
@@ -14,8 +14,9 @@ class WebhooksOnlyEventListenerSettings(EventListenerSettings):
     This class inherits from `EventListenerSettings`, which provides a foundation for creating event listener settings.
     """
 
-    type: Literal["WEBHOOKS_ONLY"]
+    type: Literal[EventListenerType.WEBHOOKS_ONLY]
     should_resync: bool = False
+    should_run_actions: bool = False
 
 
 class WebhooksOnlyEventListener(BaseEventListener):

port_ocean/core/handlers/actions/__init__.py

@@ -0,0 +1,7 @@
+from port_ocean.core.handlers.actions.abstract_executor import AbstractExecutor
+from port_ocean.core.handlers.actions.execution_manager import ExecutionManager
+
+__all__ = [
+    "AbstractExecutor",
+    "ExecutionManager",
+]

port_ocean/core/handlers/actions/abstract_executor.py

@@ -0,0 +1,150 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Type
+
+
+from port_ocean.core.handlers.webhook.abstract_webhook_processor import (
+    AbstractWebhookProcessor,
+)
+from port_ocean.core.models import ActionRun
+
+
+class AbstractExecutor(ABC):
+    """
+    Abstract base class for action executors that handle integration-specific actions.
+
+    This class defines the core interface that all action executors must implement.
+    It provides a standardized way to handle action execution, rate limiting, and
+    webhook processing for asynchronous status updates.
+
+    Class Attributes:
+        ACTION_NAME (str): The unique identifier for this action, matching the action name
+            in the integration's `.port/spec.yaml` file.
+        PARTITION_KEY (str): The key used to partition action runs for concurrent execution.
+            If provided, runs with the same partition key value will be executed sequentially.
+        WEBHOOK_PROCESSOR_CLASS (Optional[Type[AbstractWebhookProcessor]]): The webhook processor
+            class used to handle asynchronous action status updates.
+        WEBHOOK_PATH (str): The URL path where webhook events for this action should be sent.
+
+    Implementation Requirements:
+        1. Set ACTION_NAME to match the action name in the integration's `.port/spec.yaml`.
+        2. Implement rate limit checking methods to prevent API quota exhaustion.
+        3. Implement the execute method to perform the actual action logic.
+        4. Optionally set PARTITION_KEY to control concurrent execution.
+        5. Optionally provide WEBHOOK_PROCESSOR_CLASS and WEBHOOK_PATH for async updates.
+
+    Example:
+        ```python
+        class MyActionExecutor(AbstractExecutor):
+            ACTION_NAME = "my_action"
+            PARTITION_KEY = "resource_id"  # Optional
+            WEBHOOK_PROCESSOR_CLASS = MyWebhookProcessor  # Optional
+            WEBHOOK_PATH = "/webhook/my_action"  # Optional
+
+            async def is_close_to_rate_limit(self) -> bool:
+                return await self._check_rate_limit()
+
+            async def get_remaining_seconds_until_rate_limit(self) -> float:
+                return await self._get_rate_limit_wait_time()
+
+            async def execute(self, run: ActionRun) -> None:
+                # Implement action logic here
+                pass
+        ```
+    """
+
+    ACTION_NAME: str
+    WEBHOOK_PROCESSOR_CLASS: Optional[Type[AbstractWebhookProcessor]]
+    WEBHOOK_PATH: str
+
+    async def _get_partition_key(self, run: ActionRun) -> str | None:
+        """
+        This method should return a string used to identify runs that must be executed sequentially,
+        or return None to allow runs to execute in parallel.
+
+        For example, in order to execute runs of the same workflow in sequential order,
+        this method should return the workflow name.
+        """
+        return None
+
+    @abstractmethod
+    async def is_close_to_rate_limit(self) -> bool:
+        """
+        Check if the action is approaching its rate limit threshold.
+
+        This method should implement integration-specific logic to determine if
+        the action is close to hitting API rate limits. If the rate limit threshold is reached,
+        the execution manager will wait for the rate limit to reset before acknowledging the run and executing it.
+
+        Returns:
+            bool: True if the action is close to its rate limit, False otherwise.
+
+        Example:
+            ```python
+            async def is_close_to_rate_limit(self) -> bool:
+                rate_info = await self.client.get_rate_limit_info()
+                return rate_info.remaining / rate_info.limit < 0.1  # 10% threshold
+            ```
+        """
+        pass
+
+    @abstractmethod
+    async def get_remaining_seconds_until_rate_limit(self) -> float:
+        """
+        Calculate the number of seconds to wait before executing the next action.
+
+        This method should implement integration-specific logic to determine how long
+        to wait before the rate limit resets or quota becomes available. It's used
+        in conjunction with is_close_to_rate_limit() to implement backoff strategies.
+
+        Returns:
+            float: The number of seconds to wait before executing the next action.
+                  Should return 0.0 if no wait is needed.
+
+        Example:
+            ```python
+            async def get_remaining_seconds_until_rate_limit(self) -> float:
+                rate_info = await self.client.get_rate_limit_info()
+                if rate_info.reset_time > datetime.now():
+                    return (rate_info.reset_time - datetime.now()).total_seconds()
+                return 0.0
+            ```
+        """
+        pass
+
+    @abstractmethod
+    async def execute(self, run: ActionRun) -> None:
+        """
+        Execute the integration action with the provided run configuration.
+
+        Args:
+            run (ActionRun): The action run configuration
+                containing all necessary parameters and context for execution.
+
+        Raises:
+            Exception: Any error that occurs during execution. These will be caught by
+                      the execution manager and reported as run failures.
+
+        Example:
+            ```python
+            async def execute(self, run: ActionRun) -> None:
+                try:
+                    # Extract parameters
+                    params = run.payload.integrationActionExecutionProperties
+                    resource_id = params.get("resource_id")
+                    if not resource_id:
+                        raise ValueError("resource_id is required")
+
+                    # Perform action
+                    result = await self.client.update_resource(resource_id, params)
+
+                    # Update run status
+                    await ocean.port_client.patch_run(
+                        run.id,
+                        {"status": RunStatus.SUCCESS, "summary": "Resource updated"}
+                    )
+                except Exception as e:
+                    # Error will be caught by execution manager
+                    raise Exception(f"Failed to update resource: {str(e)}")
+            ```
+        """
+        pass