fastapi-gcp-tasks 0.1.0__py3-none-any.whl

fastapi_gcp_tasks/__init__.py

@@ -0,0 +1,5 @@
+# Imports from this repository
+from fastapi_gcp_tasks.delayed_route import DelayedRouteBuilder
+from fastapi_gcp_tasks.scheduled_route import ScheduledRouteBuilder
+
+__all__ = ["DelayedRouteBuilder", "ScheduledRouteBuilder"]

fastapi_gcp_tasks/decorators.py

@@ -0,0 +1,13 @@
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def task_default_options(**kwargs: Any) -> Callable[[F], F]:
+    """Wrapper to set default options for a cloud task."""
+
+    def wrapper(fn: F) -> F:
+        fn._delay_options = kwargs  # type: ignore[attr-defined]
+        return fn
+
+    return wrapper

fastapi_gcp_tasks/delayed_route.py

@@ -0,0 +1,85 @@
+# Standard Library Imports
+from typing import Callable, Type
+
+# Third Party Imports
+from fastapi.routing import APIRoute
+from google.cloud import tasks_v2
+
+# Imports from this repository
+from fastapi_gcp_tasks.delayer import Delayer
+from fastapi_gcp_tasks.hooks import DelayedTaskHook, noop_hook
+from fastapi_gcp_tasks.utils import ensure_queue
+
+
+def DelayedRouteBuilder(  # noqa: N802
+    *,
+    base_url: str,
+    queue_path: str,
+    task_create_timeout: float = 10.0,
+    pre_create_hook: DelayedTaskHook | None = None,
+    client: tasks_v2.CloudTasksClient | None = None,
+    auto_create_queue: bool = True,
+) -> Type[APIRoute]:
+    """
+    Returns a Mixin that should be used to override route_class.
+
+    It adds a .delay and .options methods to the original endpoint.
+
+    Example:
+    -------
+    ```
+      delayed_router = APIRouter(route_class=DelayedRouteBuilder(...), prefix="/delayed")
+
+      class UserData(BaseModel):
+          name: str
+
+      @delayed_router.post("/on_user_create/{user_id}")
+      def on_user_create(user_id: str, data: UserData):
+          # do work here
+          # Return values are meaningless
+
+      # Call .delay to trigger
+      on_user_create.delay(user_id="007", data=UserData(name="Piyush"))
+
+      app.include_router(delayed_router)
+    ```
+
+    """
+    if client is None:
+        client = tasks_v2.CloudTasksClient()
+
+    if pre_create_hook is None:
+        pre_create_hook = noop_hook
+
+    if auto_create_queue:
+        ensure_queue(client=client, path=queue_path)
+
+    class TaskRouteMixin(APIRoute):
+        def get_route_handler(self) -> Callable:
+            original_route_handler = super().get_route_handler()
+            self.endpoint.options = self.delay_options  # type: ignore[attr-defined]
+            self.endpoint.delay = self.delay  # type: ignore[attr-defined]
+            return original_route_handler
+
+        def delay_options(self, **options: dict) -> Delayer:
+            delay_opts = {
+                "base_url": base_url,
+                "queue_path": queue_path,
+                "task_create_timeout": task_create_timeout,
+                "client": client,
+                "pre_create_hook": pre_create_hook,
+            }
+            if hasattr(self.endpoint, "_delay_options"):
+                delay_opts |= self.endpoint._delay_options
+            delay_opts |= options
+
+            # ignoring the type here because the dictionary values are unpacked
+            return Delayer(
+                route=self,
+                **delay_opts,  # type: ignore[arg-type]
+            )
+
+        def delay(self, **kwargs: dict) -> tasks_v2.Task:
+            return self.delay_options().delay(**kwargs)
+
+    return TaskRouteMixin

fastapi_gcp_tasks/delayer.py

@@ -0,0 +1,106 @@
+# Standard Library Imports
+import datetime
+from typing import Any, Iterable
+
+# Third Party Imports
+from fastapi.routing import APIRoute
+from google.cloud import tasks_v2
+from google.protobuf import timestamp_pb2
+
+# Imports from this repository
+from fastapi_gcp_tasks.exception import BadMethodError
+from fastapi_gcp_tasks.hooks import DelayedTaskHook
+from fastapi_gcp_tasks.requester import Requester
+
+
+class Delayer(Requester):
+    """
+    A class to delay HTTP requests as tasks on Google Cloud Tasks.
+
+    Attributes
+    ----------
+        queue_path (str): The path to the Cloud Tasks queue.
+        countdown (int): The delay in seconds before the task is executed.
+        task_create_timeout (float): Timeout for creating the task.
+        task_id (str): The unique identifier for the task.
+        method (tasks_v2.HttpMethod): The HTTP method for the task.
+        client (tasks_v2.CloudTasksClient): The Cloud Tasks client.
+        pre_create_hook (DelayedTaskHook): Hook to be called before creating the task.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        route: APIRoute,
+        base_url: str,
+        queue_path: str,
+        client: tasks_v2.CloudTasksClient,
+        pre_create_hook: DelayedTaskHook,
+        task_create_timeout: float = 10.0,
+        countdown: int = 0,
+        task_id: str | None = None,
+    ) -> None:
+        super().__init__(route=route, base_url=base_url)
+        self.queue_path = queue_path
+        self.countdown = countdown
+        self.task_create_timeout = task_create_timeout
+
+        self.task_id = task_id
+        self.method = _task_method(route.methods)
+        self.client = client
+        self.pre_create_hook = pre_create_hook
+
+    def delay(self, **kwargs: Any) -> tasks_v2.Task:
+        """Delay a task on Cloud Tasks."""
+        # Create http request
+        request = tasks_v2.HttpRequest()
+        request.http_method = self.method
+        request.url = self._url(values=kwargs)
+        request.headers = self._headers(values=kwargs)
+
+        if body := self._body(values=kwargs):
+            request.body = body
+
+        # Scheduled the task
+        task = tasks_v2.Task(http_request=request)
+        if schedule_time := self._schedule():
+            task.schedule_time = schedule_time
+
+        # Make task name for deduplication
+        if self.task_id:
+            task.name = f"{self.queue_path}/tasks/{self.task_id}"
+
+        request = tasks_v2.CreateTaskRequest(parent=self.queue_path, task=task)
+
+        request = self.pre_create_hook(request)
+
+        return self.client.create_task(request=request, timeout=self.task_create_timeout)
+
+    def _schedule(self) -> timestamp_pb2.Timestamp | None:
+        if self.countdown is None or self.countdown <= 0:
+            return None
+        d = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=self.countdown)
+        timestamp = timestamp_pb2.Timestamp()
+        timestamp.FromDatetime(d)
+        return timestamp
+
+
+def _task_method(methods: Iterable[str]) -> tasks_v2.HttpMethod:
+    method_map = {
+        "POST": tasks_v2.HttpMethod.POST,
+        "GET": tasks_v2.HttpMethod.GET,
+        "HEAD": tasks_v2.HttpMethod.HEAD,
+        "PUT": tasks_v2.HttpMethod.PUT,
+        "DELETE": tasks_v2.HttpMethod.DELETE,
+        "PATCH": tasks_v2.HttpMethod.PATCH,
+        "OPTIONS": tasks_v2.HttpMethod.OPTIONS,
+    }
+    methods = list(methods)
+    # Only crash if we're being bound
+    if len(methods) > 1:
+        raise BadMethodError("Can't trigger task with multiple methods")
+    method = method_map.get(methods[0])
+    if method is None:
+        raise BadMethodError(f"Unknown method {methods[0]}")
+    return tasks_v2.HttpMethod(method)

fastapi_gcp_tasks/dependencies.py

@@ -0,0 +1,44 @@
+# Standard Library Imports
+from datetime import datetime
+from typing import Any, Callable
+
+# Third Party Imports
+from fastapi import Depends, Header, HTTPException
+
+
+def max_retries(count: int = 20) -> Callable[[Any], bool]:
+    """Raises an http exception (with status 200) after max retries are exhausted."""
+
+    def retries_dep(meta: CloudTasksHeaders = Depends()) -> bool:
+        # count starts from 0 so equality check is required
+        if meta.retry_count >= count:
+            raise HTTPException(status_code=200, detail="Max retries exhausted")
+        return True
+
+    return retries_dep
+
+
+class CloudTasksHeaders:
+    """
+    Extracts known headers sent by Cloud Tasks.
+
+    Full list: https://cloud.google.com/tasks/docs/creating-http-target-tasks#handler
+    """
+
+    def __init__(
+        self,
+        x_cloudtasks_taskretrycount: int = Header(0),
+        x_cloudtasks_taskexecutioncount: int = Header(0),
+        x_cloudtasks_queuename: str = Header(""),
+        x_cloudtasks_taskname: str = Header(""),
+        x_cloudtasks_tasketa: float = Header(0),
+        x_cloudtasks_taskpreviousresponse: int = Header(0),
+        x_cloudtasks_taskretryreason: str = Header(""),
+    ) -> None:
+        self.retry_count = x_cloudtasks_taskretrycount
+        self.execution_count = x_cloudtasks_taskexecutioncount
+        self.queue_name = x_cloudtasks_queuename
+        self.task_name = x_cloudtasks_taskname
+        self.eta = datetime.fromtimestamp(x_cloudtasks_tasketa)
+        self.previous_response = x_cloudtasks_taskpreviousresponse
+        self.retry_reason = x_cloudtasks_taskretryreason

fastapi_gcp_tasks/exception.py

@@ -0,0 +1,22 @@
+# Third Party Imports
+from pydantic.v1.errors import MissingError, PydanticValueError
+
+# TODO: Migrate to Pydantic v2.0 Errors
+
+
+class MissingParamError(MissingError):
+    """Error raised when a required parameter is missing."""
+
+    msg_template = "field required: {param}"
+
+
+class WrongTypeError(PydanticValueError):
+    """Error raised when a parameter is of the wrong type."""
+
+    msg_template = "Expected {field} to be of type {type}"
+
+
+class BadMethodError(Exception):
+    """Error raised when an invalid method is passed to a task."""
+
+    pass

fastapi_gcp_tasks/hooks.py

@@ -0,0 +1,115 @@
+# Standard Library Imports
+from typing import Any, Callable
+
+# Third Party Imports
+from google.cloud import scheduler_v1, tasks_v2
+from google.protobuf import duration_pb2
+
+DelayedTaskHook = Callable[[tasks_v2.CreateTaskRequest], tasks_v2.CreateTaskRequest]
+ScheduledHook = Callable[[scheduler_v1.CreateJobRequest], scheduler_v1.CreateJobRequest]
+
+
+def noop_hook(request: Any) -> Any:
+    """Inspired by https://github.com/kelseyhightower/nocode."""
+    return request
+
+
+def chained_hook(*hooks: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    """Call all hooks sequentially with the result from the previous hook."""
+
+    def chain(request: Any) -> Any:
+        for hook in hooks:
+            request = hook(request)
+        return request
+
+    return chain
+
+
+def oidc_scheduled_hook(token: scheduler_v1.OidcToken) -> ScheduledHook:
+    """
+    Returns a hook for ScheduledRouteBuilder to add OIDC token to all requests.
+
+    https://cloud.google.com/scheduler/docs/reference/rpc/google.cloud.scheduler.v1#google.cloud.scheduler.v1.HttpTarget
+    """
+
+    def add_token(
+        request: scheduler_v1.CreateJobRequest,
+    ) -> scheduler_v1.CreateJobRequest:
+        request.job.http_target.oidc_token = token
+        return request
+
+    return add_token
+
+
+def oidc_delayed_hook(token: tasks_v2.OidcToken) -> DelayedTaskHook:
+    """
+    Returns a hook for DelayedRouteBuilder to add OIDC token to all requests.
+
+    https://cloud.google.com/tasks/docs/reference/rpc/google.cloud.tasks.v2#google.cloud.tasks.v2.HttpRequest
+    """
+
+    def add_token(request: tasks_v2.CreateTaskRequest) -> tasks_v2.CreateTaskRequest:
+        request.task.http_request.oidc_token = token
+        return request
+
+    return add_token
+
+
+def oauth_scheduled_hook(token: scheduler_v1.OAuthToken) -> ScheduledHook:
+    """
+    Returns a hook for ScheduledRouteBuilder to add OAuth token to all requests.
+
+    https://cloud.google.com/scheduler/docs/reference/rpc/google.cloud.scheduler.v1#google.cloud.scheduler.v1.HttpTarget
+    """
+
+    def add_token(
+        request: scheduler_v1.CreateJobRequest,
+    ) -> scheduler_v1.CreateJobRequest:
+        request.job.http_target.oauth_token = token
+        return request
+
+    return add_token
+
+
+def oauth_delayed_hook(token: tasks_v2.OAuthToken) -> DelayedTaskHook:
+    """
+    Returns a hook for DelayedRouteBuilder to add OAuth token to all requests.
+
+    https://cloud.google.com/tasks/docs/reference/rpc/google.cloud.tasks.v2#google.cloud.tasks.v2.HttpRequest
+    """
+
+    def add_token(request: tasks_v2.CreateTaskRequest) -> tasks_v2.CreateTaskRequest:
+        request.task.http_request.oauth_token = token
+        return request
+
+    return add_token
+
+
+def deadline_scheduled_hook(duration: duration_pb2.Duration) -> ScheduledHook:
+    """
+    Returns a hook for ScheduledRouteBuilder to set Deadline for job execution.
+
+    https://cloud.google.com/scheduler/docs/reference/rpc/google.cloud.scheduler.v1#google.cloud.scheduler.v1.Job
+    """
+
+    def deadline(
+        request: scheduler_v1.CreateJobRequest,
+    ) -> scheduler_v1.CreateJobRequest:
+        request.job.attempt_deadline = duration
+        return request
+
+    return deadline
+
+
+def deadline_delayed_hook(duration: duration_pb2.Duration) -> DelayedTaskHook:
+    """
+    Returns a hook for DelayedRouteBuilder to set Deadline for task execution.
+
+    https://cloud.google.com/tasks/docs/reference/rpc/google.cloud.tasks.v2#google.cloud.tasks.v2.Task
+    """
+
+    def deadline(request: tasks_v2.CreateTaskRequest) -> tasks_v2.CreateTaskRequest:
+        request.task.dispatch_deadline = duration
+        return request
+
+    return deadline

fastapi_gcp_tasks/requester.py

@@ -0,0 +1,105 @@
+# Standard Library Imports
+from typing import Any, Dict, List, Tuple
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+# Third Party Imports
+from fastapi.dependencies.utils import request_params_to_args
+from fastapi.encoders import jsonable_encoder
+from fastapi.routing import APIRoute
+from pydantic.v1.error_wrappers import ErrorWrapper
+
+# Imports from this repository
+from fastapi_gcp_tasks.exception import MissingParamError, WrongTypeError
+
+try:
+    # Third Party Imports
+    import ujson as json
+except ImportError:
+    # Standard Library Imports
+    import json  # type: ignore[no-redef]
+
+
+class Requester:
+    """
+    A class to construct HTTP requests based on FastAPI routes, handling headers, URL construction, and request bodies.
+
+    Attributes
+    ----------
+        route (APIRoute): The FastAPI route object.
+        base_url (str): The base URL for the requests.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        route: APIRoute,
+        base_url: str,
+    ) -> None:
+        self.route = route
+        self.base_url = base_url.rstrip("/")
+
+    def _headers(self, *, values: Dict[str, Any]) -> Dict[str, str]:
+        headers = _err_val(request_params_to_args(self.route.dependant.header_params, values))
+        cookies = _err_val(request_params_to_args(self.route.dependant.cookie_params, values))
+        if len(cookies) > 0:
+            headers["Cookies"] = "; ".join([f"{k}={v}" for (k, v) in cookies.items()])
+        # We use json only.
+        headers["Content-Type"] = "application/json"
+        # Always send string headers and skip all headers which are supposed to be sent by cloudtasks
+        return {str(k): str(v) for (k, v) in headers.items() if not str(k).startswith("x_cloudtasks_")}
+
+    def _url(self, *, values: Dict[str, Any]) -> str:
+        route = self.route
+        path_values = _err_val(request_params_to_args(route.dependant.path_params, values))
+        for name, converter in route.param_convertors.items():
+            if name in path_values:
+                continue
+            if name not in values:
+                raise MissingParamError(param=name)
+
+            # TODO: should we catch errors here and raise better errors?
+            path_values[name] = converter.convert(values[name])
+        path = route.path_format.format(**path_values)
+        params = _err_val(request_params_to_args(route.dependant.query_params, values))
+
+        # Make final URL
+
+        # Split base url into parts
+        url_parts = list(urlparse(self.base_url))
+
+        # Add relative path
+        # Note: you might think urljoin is a better solution here, it is not.
+        url_parts[2] = url_parts[2].strip("/") + "/" + path.strip("/")
+
+        # Make query dict and update our with our params
+        query = dict(parse_qsl(url_parts[4]))
+        query.update(params)
+
+        # override query params
+        url_parts[4] = urlencode(query)
+        return urlunparse(url_parts)
+
+    def _body(self, *, values: Dict[str, Any]) -> bytes | None:
+        body = None
+        body_field = self.route.body_field
+        if body_field and body_field.name:
+            got_body = values.get(body_field.name)
+            if got_body is None:
+                if body_field.required:
+                    raise MissingParamError(name=body_field.name)
+                got_body = body_field.get_default()
+            if not isinstance(got_body, body_field.type_):
+                raise WrongTypeError(field=body_field.name, type=body_field.type_)
+            body = json.dumps(jsonable_encoder(got_body)).encode()
+        return body
+
+
+def _err_val(resp: Tuple[Dict, List[ErrorWrapper]]) -> Dict:
+    values, errors = resp
+
+    if len(errors) != 0:
+        # TODO: Log everything but raise first only
+        # TODO: find a better way to raise and display these errors
+        raise errors[0].exc
+    return values

fastapi_gcp_tasks/scheduled_route.py

@@ -0,0 +1,67 @@
+# Standard Library Imports
+from typing import Callable, Type
+
+# Third Party Imports
+from fastapi.routing import APIRoute
+from google.cloud import scheduler_v1
+
+# Imports from this repository
+from fastapi_gcp_tasks.hooks import ScheduledHook, noop_hook
+from fastapi_gcp_tasks.scheduler import Scheduler
+
+
+def ScheduledRouteBuilder(  # noqa: N802
+    *,
+    base_url: str,
+    location_path: str,
+    job_create_timeout: float = 10.0,
+    pre_create_hook: ScheduledHook | None = None,
+    client: scheduler_v1.CloudSchedulerClient | None = None,
+) -> Type[APIRoute]:
+    """
+    Returns a Mixin that should be used to override route_class.
+
+    It adds a .scheduler method to the original endpoint.
+
+    Example:
+    -------
+    ```
+    scheduled_router = APIRouter(route_class=ScheduledRouteBuilder(...), prefix="/scheduled")
+
+    @scheduled_router.get("/simple_scheduled_task")
+    def simple_scheduled_task():
+        # Do work here
+
+    simple_scheduled_task.scheduler(name="simple_scheduled_task", schedule="* * * * *").schedule()
+
+    app.include_router(scheduled_router)
+    ```
+
+    """
+    if client is None:
+        client = scheduler_v1.CloudSchedulerClient()
+
+    if pre_create_hook is None:
+        pre_create_hook = noop_hook
+
+    class ScheduledRouteMixin(APIRoute):
+        def get_route_handler(self) -> Callable:
+            original_route_handler = super().get_route_handler()
+            self.endpoint.scheduler = self.scheduler_options  # type: ignore[attr-defined]
+            return original_route_handler
+
+        def scheduler_options(self, *, name: str, schedule: str, **options: dict) -> Scheduler:
+            scheduler_opts = {
+                "base_url": base_url,
+                "location_path": location_path,
+                "client": client,
+                "pre_create_hook": pre_create_hook,
+                "job_create_timeout": job_create_timeout,
+                "name": name,
+                "schedule": schedule,
+            } | options
+
+            # ignoring the type here because the dictionary values are unpacked
+            return Scheduler(route=self, **scheduler_opts)  # type: ignore[arg-type]
+
+    return ScheduledRouteMixin

fastapi_gcp_tasks/scheduler.py

@@ -0,0 +1,152 @@
+# Standard Library Imports
+from typing import Any, Iterable
+
+# Third Party Imports
+from fastapi.routing import APIRoute
+from google.cloud import scheduler_v1
+from google.protobuf import duration_pb2
+
+# Imports from this repository
+from fastapi_gcp_tasks.exception import BadMethodError
+from fastapi_gcp_tasks.hooks import ScheduledHook
+from fastapi_gcp_tasks.requester import Requester
+
+
+class Scheduler(Requester):
+    """
+    A class to schedule HTTP requests as jobs on Google Cloud Scheduler.
+
+    Attributes
+    ----------
+        retry_config (scheduler_v1.RetryConfig): Configuration for retrying failed jobs.
+        job_id (str): The unique identifier for the job.
+        time_zone (str): The time zone for the job schedule.
+        location_path (str): The location path for the job.
+        cron_schedule (str): The cron schedule for the job.
+        job_create_timeout (float): Timeout for creating the job.
+        method (scheduler_v1.HttpMethod): The HTTP method for the job.
+        client (scheduler_v1.CloudSchedulerClient): The Cloud Scheduler client.
+        pre_create_hook (ScheduledHook): Hook to be called before creating the job.
+        force (bool): Whether to force create the job if it already exists.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        route: APIRoute,
+        base_url: str,
+        location_path: str,
+        schedule: str,
+        client: scheduler_v1.CloudSchedulerClient,
+        pre_create_hook: ScheduledHook,
+        name: str = "",
+        job_create_timeout: float = 10.0,
+        retry_config: scheduler_v1.RetryConfig | None = None,
+        time_zone: str = "UTC",
+        force: bool = False,
+    ) -> None:
+        super().__init__(route=route, base_url=base_url)
+        if not name:
+            name = route.unique_id
+
+        if retry_config is None:
+            retry_config = scheduler_v1.RetryConfig(
+                retry_count=5,
+                max_retry_duration=duration_pb2.Duration(seconds=0),
+                min_backoff_duration=duration_pb2.Duration(seconds=5),
+                max_backoff_duration=duration_pb2.Duration(seconds=120),
+                max_doublings=5,
+            )
+
+        self.retry_config = retry_config
+        location_parts = client.parse_common_location_path(location_path)
+
+        self.job_id = client.job_path(job=name, **location_parts)
+        self.time_zone = time_zone
+
+        self.location_path = location_path
+        self.cron_schedule = schedule
+        self.job_create_timeout = job_create_timeout
+
+        self.method = _scheduler_method(route.methods)
+        self.client = client
+        self.pre_create_hook = pre_create_hook
+        self.force = force
+
+    def schedule(self, **kwargs: Any) -> None:
+        """Schedule a job on Cloud Scheduler."""
+        # Create http request
+        request = scheduler_v1.HttpTarget()
+        request.http_method = self.method
+        request.uri = self._url(values=kwargs)
+        request.headers = self._headers(values=kwargs)
+
+        body = self._body(values=kwargs)
+        if body:
+            request.body = body
+
+        # Scheduled the task
+        job = scheduler_v1.Job(
+            name=self.job_id,
+            http_target=request,
+            schedule=self.cron_schedule,
+            retry_config=self.retry_config,
+            time_zone=self.time_zone,
+        )
+
+        request = scheduler_v1.CreateJobRequest(parent=self.location_path, job=job)
+
+        request = self.pre_create_hook(request)
+
+        if self.force or self._has_changed(request=request):
+            # Delete and create job
+            self.delete()
+            self.client.create_job(request=request, timeout=self.job_create_timeout)
+
+    def _has_changed(self, request: scheduler_v1.CreateJobRequest) -> bool:
+        try:
+            job = self.client.get_job(name=request.job.name)
+            # Remove things that are either output only or GCP adds by default
+            job.user_update_time = None  # type: ignore[assignment]
+            job.state = None  # type: ignore[assignment]
+            job.status = None
+            job.last_attempt_time = None  # type: ignore[assignment]
+            job.schedule_time = None  # type: ignore[assignment]
+            del job.http_target.headers["User-Agent"]
+            # Proto compare works directly with `__eq__`
+            return job != request.job
+        # TODO: replace this with a more specific exception
+        except Exception:  # noqa: BLE001
+            return True
+        return False
+
+    def delete(self) -> bool | Exception:
+        """Delete the job from the scheduler if it exists."""
+        # We return true or exception because you could have the delete code on multiple instances
+        try:
+            self.client.delete_job(name=self.job_id, timeout=self.job_create_timeout)
+            return True
+        # TODO: replace this with a more specific exception. we may also just raise the exception here?
+        except Exception as ex:  # noqa: BLE001
+            return ex
+
+
+def _scheduler_method(methods: Iterable[str]) -> scheduler_v1.HttpMethod:
+    method_map = {
+        "POST": scheduler_v1.HttpMethod.POST,
+        "GET": scheduler_v1.HttpMethod.GET,
+        "HEAD": scheduler_v1.HttpMethod.HEAD,
+        "PUT": scheduler_v1.HttpMethod.PUT,
+        "DELETE": scheduler_v1.HttpMethod.DELETE,
+        "PATCH": scheduler_v1.HttpMethod.PATCH,
+        "OPTIONS": scheduler_v1.HttpMethod.OPTIONS,
+    }
+    methods = list(methods)
+    # Only crash if we're being bound
+    if len(methods) > 1:
+        raise BadMethodError("Can't schedule task with multiple methods")
+    method = method_map.get(methods[0])
+    if method is None:
+        raise BadMethodError(f"Unknown method {methods[0]}")
+    return scheduler_v1.HttpMethod(method)

fastapi_gcp_tasks/utils.py

@@ -0,0 +1,48 @@
+# Third Party Imports
+from typing import Any
+
+import grpc
+from google.api_core.exceptions import AlreadyExists
+from google.cloud import scheduler_v1, tasks_v2
+from google.cloud.tasks_v2.services.cloud_tasks import transports
+
+
+def location_path(*, project: str, location: str) -> str:
+    """Helper function to construct a location path for Cloud Scheduler."""
+    return scheduler_v1.CloudSchedulerClient.common_location_path(project=project, location=location)
+
+
+def queue_path(*, project: str, location: str, queue: str) -> str:
+    """Helper function to construct a queue path for Cloud Tasks."""
+    return tasks_v2.CloudTasksClient.queue_path(project=project, location=location, queue=queue)
+
+
+def ensure_queue(
+    *,
+    client: tasks_v2.CloudTasksClient,
+    path: str,
+    **kwargs: Any,
+) -> None:
+    """
+    Helper function to ensure a Cloud Tasks queue exists.
+
+    If the queue already exists, this function will not raise an error.
+    If the queue does not exist, it will be created with the provided kwargs.
+    """
+    # We extract information from the queue path to make the public api simpler
+    parsed_queue_path = client.parse_queue_path(path=path)
+    create_req = tasks_v2.CreateQueueRequest(
+        parent=location_path(**parsed_queue_path),
+        queue=tasks_v2.Queue(name=path, **kwargs),
+    )
+    try:
+        client.create_queue(request=create_req)
+    except AlreadyExists:
+        pass
+
+
+def emulator_client(*, host: str = "localhost:8123") -> tasks_v2.CloudTasksClient:
+    """Helper function to create a CloudTasksClient from an emulator host."""
+    channel = grpc.insecure_channel(host)
+    transport = transports.CloudTasksGrpcTransport(channel=channel)
+    return tasks_v2.CloudTasksClient(transport=transport)

fastapi_gcp_tasks-0.1.0.dist-info/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Simplify Jobs, Inc
+Copyright (c) 2021 Adori Labs, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_gcp_tasks-0.1.0.dist-info/METADATA

@@ -0,0 +1,399 @@
+Metadata-Version: 2.1
+Name: fastapi-gcp-tasks
+Version: 0.1.0
+Summary: Trigger delayed Cloud Tasks from FastAPI
+License: MIT
+Author: Team Simplify
+Author-email: oss@simplify.jobs
+Requires-Python: >=3.11,<3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastapi (>=0.110.0,<0.120.0)
+Requires-Dist: google-cloud-scheduler (>=2.13.3,<2.20.0)
+Requires-Dist: google-cloud-tasks (>=2.16.3,<2.20.0)
+Description-Content-Type: text/markdown
+
+# FastAPI Cloud Tasks
+
+Strongly typed background tasks with FastAPI and Google CloudTasks. This is a fork of [fastapi-gcp-tasks](https://github.com/adori/fastapi-gcp-tasks), updated with new features and bug fixes.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Service
+    participant CloudTasks
+    participant Worker
+
+
+    User ->>+ Service: /trigger
+
+
+    rect rgb(100,130,180)
+    note right of Service: hello.delay()
+    Service -->>+ CloudTasks: Create task
+    CloudTasks -->>- Service: Accepted
+    end
+
+    Service ->>- User: Hello task triggered
+    note right of CloudTasks: Async
+    CloudTasks -->>+ Worker: /hello
+    Worker -->>- CloudTasks: 200
+
+```
+
+## Installation
+
+```
+pip install fastapi-gcp-tasks
+```
+
+## Key features
+
+- Strongly typed tasks.
+  - Fail at invocation site to make it easier to develop and debug.
+  - Breaking schema changes between versions will fail at task runner with Pydantic.
+- Familiar and simple public API
+  - `.delay` method that takes same arguments as the task.
+  - `.scheduler` method to create recurring job.
+- Tasks are regular FastAPI endpoints on plain old HTTP.
+  - `Depends` just works!
+  - All middlewares, telemetry, auth, debugging etc solutions for FastAPI work as is.
+  - Host task runners independent of GCP. If CloudTasks can reach the URL, it can invoke the task.
+- Save money.
+  - Task invocation with GCP is [free for first million, then costs $0.4/million](https://cloud.google.com/tasks/pricing).
+    That's almost always cheaper than running a RabbitMQ/Redis/SQL backend for celery.
+  - Jobs cost [$0.1 per job per month irrespective of invocations. 3 jobs are free.](https://cloud.google.com/scheduler#pricing)
+    Either free or almost always cheaper than always running beat worker.
+  - If somehow, this cost ever becomes a concern, the `client` can be overriden to call any gRPC server with a compatible API.
+    [Here's a trivial emulator implementation that we will use locally](https://github.com/aertje/cloud-tasks-emulator)
+- Autoscale.
+  - With a FaaS setup, your task workers can autoscale based on load.
+  - Most FaaS services have free tiers making it much cheaper than running a celery worker.
+
+## How it works
+
+### Delayed job
+
+```python
+from fastapi_gcp_tasks import DelayedRouteBuilder
+
+delayed_router = APIRouter(route_class=DelayedRouteBuilder(...))
+
+
+class Recipe(BaseModel):
+  ingredients: List[str]
+
+
+@delayed_router.post("/{restaurant}/make_dinner")
+async def make_dinner(restaurant: str, recipe: Recipe):
+
+
+# Do a ton of work here.
+
+
+app.include_router(delayed_router)
+```
+
+Now we can trigger the task with
+
+```python
+make_dinner.delay(restaurant="Taj", recipe=Recipe(ingredients=["Pav","Bhaji"]))
+```
+
+If we want to trigger the task 30 minutes later
+
+```python
+make_dinner.options(countdown=1800).delay(...)
+```
+
+### Scheduled Task
+
+```python
+from fastapi_gcp_tasks import ScheduledRouteBuilder
+
+scheduled_router = APIRouter(route_class=ScheduledRouteBuilder(...))
+
+
+class Recipe(BaseModel):
+  ingredients: List[str]
+
+
+@scheduled_router.post("/home_cook")
+async def home_cook(recipe: Recipe):
+
+
+# Make my own food
+
+app.include_router(scheduled_router)
+
+# If you want to make your own breakfast every morning at 7AM IST.
+home_cook.scheduler(name="test-home-cook-at-7AM-IST", schedule="0 7 * * *", time_zone="Asia/Kolkata").schedule(
+  recipe=Recipe(ingredients=["Milk", "Cereal"]))
+```
+
+## Concept
+
+[`Cloud Tasks`](https://cloud.google.com/tasks) allows us to schedule a HTTP request in the future.
+
+[FastAPI](https://fastapi.tiangolo.com/tutorial/body/) makes us define complete schema and params for an HTTP endpoint.
+
+[`Cloud Scheduler`](https://cloud.google.com/scheduler) allows us to schedule recurring HTTP requests in the future.
+
+FastAPI Cloud Tasks works by putting the three together:
+
+- GCP's Cloud Tasks + FastAPI = Partial replacement for celery's async delayed tasks.
+- GCP's Cloud Scheduler + FastAPI = Replacement for celery beat.
+- FastAPI Cloud Tasks + Cloud Run = Autoscaled delayed tasks.
+
+
+
+## Running
+
+### Local
+
+Pre-requisites:
+- `pip install fastapi-gcp-tasks`
+- Install [cloud-tasks-emulator](https://github.com/aertje/cloud-tasks-emulator)
+  - Alternatively install ngrok and forward the server's port
+
+Start running the emulator in a terminal
+```sh
+cloud-tasks-emulator
+```
+
+Start running the task runner on port 8000 so that it is accessible from cloud tasks.
+
+```sh
+uvicorn examples.simple.main:app --reload --port 8000
+```
+
+In another terminal, trigger the task with curl
+
+```
+curl http://localhost:8000/trigger
+```
+
+Check the logs on the server, you should see
+
+```
+WARNING:  Hello task ran with payload: Triggered task
+```
+
+Important bits of code:
+
+```python
+# complete file: examples/simple/main.py
+
+# For local, we connect to the emulator client
+client = None
+if IS_LOCAL:
+ client = emulator_client()
+
+# Construct our DelayedRoute class with all relevant settings
+# This can be done once across the entire project
+DelayedRoute = DelayedRouteBuilder(
+    client=client,
+    base_url="http://localhost:8000"
+    queue_path=queue_path(
+        project="gcp-project-id",
+        location="asia-south1",
+        queue="test-queue",
+    ),
+)
+
+# Override the route_class so that we can add .delay method to the endpoints and know their complete URL
+delayed_router = APIRouter(route_class=DelayedRoute, prefix="/delayed")
+
+class Payload(BaseModel):
+    message: str
+
+@delayed_router.post("/hello")
+async def hello(p: Payload = Payload(message="Default")):
+    logger.warning(f"Hello task ran with payload: {p.message}")
+
+
+# Define our app and add trigger to it.
+app = FastAPI()
+
+@app.get("/trigger")
+async def trigger():
+    # Trigger the task
+    hello.delay(p=Payload(message="Triggered task"))
+    return {"message": "Hello task triggered"}
+
+app.include_router(delayed_router)
+
+```
+
+Note: You can read complete working source code of the above example in [`examples/simple/main.py`](examples/simple/main.py)
+
+In the real world you'd have a separate process for task runner and actual task.
+
+### Deployed environment / Cloud Run
+
+Running on Cloud Run with authentication needs us to supply an OIDC token. To do that we can use a `hook`.
+
+Pre-requisites:
+
+- Create a task queue. Copy the project id, location and queue name.
+- Deploy the worker as a service on Cloud Run and copy it's URL.
+- Create a service account in cloud IAM and add `Cloud Run Invoker` role to it.
+
+
+```python
+# URL of the Cloud Run service
+base_url = "https://hello-randomchars-el.a.run.app"
+
+DelayedRoute = DelayedRouteBuilder(
+    base_url=base_url,
+    # Task queue, same as above.
+    queue_path=queue_path(...),
+    pre_create_hook=oidc_task_hook(
+        token=tasks_v2.OidcToken(
+            # Service account that you created
+            service_account_email="fastapi-gcp-tasks@gcp-project-id.iam.gserviceaccount.com",
+            audience=base_url,
+        ),
+    ),
+)
+```
+
+Check the fleshed out example at [`examples/full/tasks.py`](examples/full/tasks.py)
+
+If you're not running on CloudRun and want to an OAuth Token instead, you can use the `oauth_task_hook` instead.
+
+Check [fastapi_cloud_tasks/hooks.py](fastapi_gcp_tasks/hooks.py) to get the hang od hooks and how you can use them.
+
+## Configuration
+
+### DelayedRouteBuilder
+
+Usage:
+
+```python
+DelayedRoute = DelayedRouteBuilder(...)
+delayed_router = APIRouter(route_class=DelayedRoute)
+
+@delayed_router.get("/simple_task")
+def simple_task():
+    return {}
+```
+
+- `base_url` - The URL of your worker FastAPI service.
+
+- `queue_path` - Full path of the Cloud Tasks queue. (Hint: use the util function `queue_path`)
+
+- `task_create_timeout` - How long should we wait before giving up on creating cloud task.
+
+- `pre_create_hook` - If you need to edit the `CreateTaskRequest` before sending it to Cloud Tasks (eg: Auth for Cloud Run), you can do that with this hook. See hooks section below for more.
+
+- `client` - If you need to override the Cloud Tasks client, pass the client here. (eg: changing credentials, transport etc)
+
+#### Task level default options
+
+Usage:
+
+```python
+@delayed_router.get("/simple_task")
+@task_default_options(...)
+def simple_task():
+    return {}
+```
+
+All options from above can be passed as `kwargs` to the decorator.
+
+Additional options:
+
+- `countdown` - Seconds in the future to schedule the task.
+- `task_id` - named task id for deduplication. (One task id will only be queued once.)
+
+Example:
+
+```python
+# Trigger after 5 minutes
+@delayed_router.get("/simple_task")
+@task_default_options(countdown=300)
+def simple_task():
+    return {}
+```
+
+#### Delayer Options
+
+Usage:
+
+```python
+simple_task.options(...).delay()
+```
+
+All options from above can be overwritten per call (including DelayedRouteBuilder options like `base_url`) with kwargs to the `options` function before calling delay.
+
+Example:
+
+```python
+# Trigger after 2 minutes
+simple_task.options(countdown=120).delay()
+```
+
+### ScheduledRouteBuilder
+
+Usage:
+
+```python
+ScheduledRoute = ScheduledRouteBuilder(...)
+scheduled_router = APIRouter(route_class=ScheduledRoute)
+
+@scheduled_router.get("/simple_scheduled_task")
+def simple_scheduled_task():
+    return {}
+
+
+simple_scheduled_task.scheduler(name="simple_scheduled_task", schedule="* * * * *").schedule()
+```
+
+
+## Hooks
+
+We might need to override things in the task being sent to Cloud Tasks. The `pre_create_hook` allows us to do that.
+
+Some hooks are included in the library.
+
+- `oidc_delayed_hook` / `oidc_scheduled_hook` - Used to pass OIDC token (for Cloud Run etc).
+- `deadline_delayed_hook` / `deadline_scheduled_hook` - Used to change the timeout for the worker of a task. (PS: this deadline is decided by the sender to the queue and not the worker)
+- `chained_hook` - If you need to chain multiple hooks together, you can do that with `chained_hook(hook1, hook2)`
+
+## Helper dependencies
+
+### max_retries
+
+```python
+@delayed_router.post("/fail_twice", dependencies=[Depends(max_retries(2))])
+async def fail_twice():
+    raise Exception("nooo")
+```
+
+### CloudTasksHeaders
+
+```python
+@delayed_router.get("/my_task")
+async def my_task(ct_headers: CloudTasksHeaders = Depends()):
+    print(ct_headers.queue_name)
+```
+
+Check the file [fastapi_cloud_tasks/dependencies.py](fastapi_gcp_tasks/dependencies.py) for details.
+
+## Contributing
+
+- Run the `format.sh` and `lint.sh` scripts before raising a PR.
+- Add examples and/or tests for new features.
+- If the change is massive, open an issue to discuss it before writing code.
+
+## License
+
+This project is licensed under the terms of the MIT license. This project was forked from [fastapi-gcp-tasks](https://github.com/Adori/fastapi-gcp-tasks) under the MIT license. All changes made to the original project are also licensed under the MIT license.
+
+## Disclaimer
+
+This project is neither affiliated with, nor sponsored by Google.

fastapi_gcp_tasks-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+fastapi_gcp_tasks/__init__.py,sha256=PJCDGps4nkDIVqYteR_Spj-vnAdNrulvBs7I-UWBg4I,223
+fastapi_gcp_tasks/decorators.py,sha256=1MVCd8j64WIwfciOUtTk_7bm82Xwoo2CezDzpS0mB3U,341
+fastapi_gcp_tasks/delayed_route.py,sha256=g2S3gFuqOMdIb7WavAxCmH4KRgTXxsBXv0kqUJMY5r8,2695
+fastapi_gcp_tasks/delayer.py,sha256=wlaKYxpW1FHeukU1b1vl5ob7ttYD1FmdEnMcU0v-VzQ,3687
+fastapi_gcp_tasks/dependencies.py,sha256=vU6jIkRL1cHY8scTDTukI8Z6Gj_TGevWe6O7HzyXMCg,1605
+fastapi_gcp_tasks/exception.py,sha256=j73Wnp8hvFt2KcsIa02PLNAI5g19GzmppbfgUhw5S6Y,553
+fastapi_gcp_tasks/hooks.py,sha256=Lycd2W-5GzpUvVdIv52O9fzJ_svyPhM_v0WH_N73w9w,3637
+fastapi_gcp_tasks/requester.py,sha256=hW4MWdTw8FLqTUX7uY7xO2GT5x-kj6u-Vt6p1SkL0Ms,3872
+fastapi_gcp_tasks/scheduled_route.py,sha256=uVXbTmWWB1eYGTzkktuPpW8HmHECG_42E48EOW_EfDU,2175
+fastapi_gcp_tasks/scheduler.py,sha256=jRYxfMDIJi7kIwM97WXLokKu1HgxSKvwutxd0eLkdd0,5768
+fastapi_gcp_tasks/utils.py,sha256=cWmb3Hp_ARC_7jzlWJqmBev5p6_AQ8-3x82y4uQ6Vck,1754
+fastapi_gcp_tasks-0.1.0.dist-info/LICENSE,sha256=MZNVfvWc_pvZ3mRsL-THDNaozD4Xv_QRjpoAe1-ghSY,1110
+fastapi_gcp_tasks-0.1.0.dist-info/METADATA,sha256=Z_scg3XKbr8DgAurYe9zekzGbnDhZyORC5-hn0xASA0,11416
+fastapi_gcp_tasks-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+fastapi_gcp_tasks-0.1.0.dist-info/RECORD,,

fastapi_gcp_tasks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any