queueflow 0.1.0__py3-none-any.whl

queueflow/models/heartbeat_request.py

@@ -0,0 +1,90 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictStr
+from typing import Any, ClassVar, Dict, List
+from typing_extensions import Annotated
+from typing import Optional, Set
+from typing_extensions import Self
+
+class HeartbeatRequest(BaseModel):
+    """
+    Body for `POST /api/v1/jobs/{id}/heartbeat`.
+    """ # noqa: E501
+    extend_secs: Annotated[int, Field(strict=True, ge=0)] = Field(description="New lease duration in seconds, measured from now (1..=3600).")
+    lease_token: StrictStr = Field(description="The lease token returned by the lease call.")
+    __properties: ClassVar[List[str]] = ["extend_secs", "lease_token"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of HeartbeatRequest from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of HeartbeatRequest from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "extend_secs": obj.get("extend_secs"),
+            "lease_token": obj.get("lease_token")
+        })
+        return _obj
+
+

queueflow/models/heartbeat_response.py

@@ -0,0 +1,88 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Any, ClassVar, Dict, List
+from queueflow.models.job_status import JobStatus
+from typing import Optional, Set
+from typing_extensions import Self
+
+class HeartbeatResponse(BaseModel):
+    """
+    Response for `POST /api/v1/jobs/{id}/heartbeat`.
+    """ # noqa: E501
+    status: JobStatus = Field(description="The job's current status. `running` means the lease was extended; anything else (`cancelled`, `completed`, ...) means it was not, and the worker should stop working on the job.")
+    __properties: ClassVar[List[str]] = ["status"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of HeartbeatResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of HeartbeatResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "status": obj.get("status")
+        })
+        return _obj
+
+

queueflow/models/job.py

@@ -0,0 +1,172 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict, Field, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional
+from typing_extensions import Annotated
+from queueflow.models.job_config import JobConfig
+from queueflow.models.job_status import JobStatus
+from typing import Optional, Set
+from typing_extensions import Self
+
+class Job(BaseModel):
+    """
+    A single unit of work.
+    """ # noqa: E501
+    completed_at: Optional[datetime] = None
+    config: JobConfig
+    created_at: datetime
+    delivery_count: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="How many times this job has been claimed (delivered to a worker). Greater than `retry_count + 1` means a lease expired without a report — i.e. a worker crashed mid-run.")
+    error_message: Optional[StrictStr] = None
+    id: StrictStr
+    idempotency_key: Optional[StrictStr] = Field(default=None, description="Client-supplied key that makes job creation idempotent per tenant: re-submitting the same key returns the original job instead of creating a duplicate.")
+    metadata: Optional[Dict[str, Any]] = None
+    next_retry_at: Optional[datetime] = Field(default=None, description="When this job's next retry becomes claimable (mirrors `scheduled_at` while the job is `retrying`; kept for audit/inspection).")
+    payload: Optional[Dict[str, Any]] = None
+    queue_name: StrictStr
+    result: Optional[Dict[str, Any]] = None
+    retry_count: Annotated[int, Field(strict=True, ge=0)]
+    scheduled_at: datetime = Field(description="When the job becomes claimable. `created_at` for immediate jobs, the requested `run_at` for scheduled jobs, and the next backoff instant while retrying — the durable delay lives in the row itself.")
+    started_at: Optional[datetime] = None
+    status: JobStatus
+    task_name: StrictStr
+    tenant_id: Optional[StrictStr] = None
+    workflow_id: Optional[StrictStr] = None
+    workflow_step_id: Optional[StrictStr] = Field(default=None, description="The owning workflow step's name (steps are addressed by name).")
+    __properties: ClassVar[List[str]] = ["completed_at", "config", "created_at", "delivery_count", "error_message", "id", "idempotency_key", "metadata", "next_retry_at", "payload", "queue_name", "result", "retry_count", "scheduled_at", "started_at", "status", "task_name", "tenant_id", "workflow_id", "workflow_step_id"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of Job from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # override the default output from pydantic by calling `to_dict()` of config
+        if self.config:
+            _dict['config'] = self.config.to_dict()
+        # set to None if completed_at (nullable) is None
+        # and model_fields_set contains the field
+        if self.completed_at is None and "completed_at" in self.model_fields_set:
+            _dict['completed_at'] = None
+
+        # set to None if error_message (nullable) is None
+        # and model_fields_set contains the field
+        if self.error_message is None and "error_message" in self.model_fields_set:
+            _dict['error_message'] = None
+
+        # set to None if idempotency_key (nullable) is None
+        # and model_fields_set contains the field
+        if self.idempotency_key is None and "idempotency_key" in self.model_fields_set:
+            _dict['idempotency_key'] = None
+
+        # set to None if next_retry_at (nullable) is None
+        # and model_fields_set contains the field
+        if self.next_retry_at is None and "next_retry_at" in self.model_fields_set:
+            _dict['next_retry_at'] = None
+
+        # set to None if started_at (nullable) is None
+        # and model_fields_set contains the field
+        if self.started_at is None and "started_at" in self.model_fields_set:
+            _dict['started_at'] = None
+
+        # set to None if tenant_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.tenant_id is None and "tenant_id" in self.model_fields_set:
+            _dict['tenant_id'] = None
+
+        # set to None if workflow_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.workflow_id is None and "workflow_id" in self.model_fields_set:
+            _dict['workflow_id'] = None
+
+        # set to None if workflow_step_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.workflow_step_id is None and "workflow_step_id" in self.model_fields_set:
+            _dict['workflow_step_id'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of Job from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "completed_at": obj.get("completed_at"),
+            "config": JobConfig.from_dict(obj["config"]) if obj.get("config") is not None else None,
+            "created_at": obj.get("created_at"),
+            "delivery_count": obj.get("delivery_count"),
+            "error_message": obj.get("error_message"),
+            "id": obj.get("id"),
+            "idempotency_key": obj.get("idempotency_key"),
+            "metadata": obj.get("metadata"),
+            "next_retry_at": obj.get("next_retry_at"),
+            "payload": obj.get("payload"),
+            "queue_name": obj.get("queue_name"),
+            "result": obj.get("result"),
+            "retry_count": obj.get("retry_count"),
+            "scheduled_at": obj.get("scheduled_at"),
+            "started_at": obj.get("started_at"),
+            "status": obj.get("status"),
+            "task_name": obj.get("task_name"),
+            "tenant_id": obj.get("tenant_id"),
+            "workflow_id": obj.get("workflow_id"),
+            "workflow_step_id": obj.get("workflow_step_id")
+        })
+        return _obj
+
+

queueflow/models/job_config.py

@@ -0,0 +1,106 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictInt
+from typing import Any, ClassVar, Dict, List, Optional, Union
+from typing_extensions import Annotated
+from queueflow.models.backoff_strategy import BackoffStrategy
+from typing import Optional, Set
+from typing_extensions import Self
+
+class JobConfig(BaseModel):
+    """
+    Per-job execution configuration. All durations are in seconds.  Deserialization is partial-friendly: any omitted field takes its [`JobConfig::default`] value (via per-field serde defaults), so workflow-step and cron config overrides can name just the fields they change, and out-of-band rows with sparse `config` JSONB still load. Per-field functions rather than a struct-level `#[serde(default)]`: the struct-level form makes utoipa attach a `default` beside the `BackoffStrategy` `$ref`, which forces a synthetic wrapper type into every generated SDK.
+    """ # noqa: E501
+    jitter_factor: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="Optional jitter in `0.0..=1.0`. `0.1` => +/-10% randomization of each retry delay, which spreads out thundering-herd retries.")
+    max_retries: Optional[Annotated[int, Field(strict=True, ge=0)]] = None
+    priority: Optional[StrictInt] = Field(default=None, description="Higher is claimed first within a queue; ties break on `scheduled_at`, then `created_at`.")
+    retry_backoff: Optional[BackoffStrategy] = None
+    retry_delay_secs: Optional[Annotated[int, Field(strict=True, ge=0)]] = None
+    retry_max_delay_secs: Optional[Annotated[int, Field(strict=True, ge=0)]] = None
+    timeout_secs: Optional[Annotated[int, Field(strict=True, ge=0)]] = None
+    __properties: ClassVar[List[str]] = ["jitter_factor", "max_retries", "priority", "retry_backoff", "retry_delay_secs", "retry_max_delay_secs", "timeout_secs"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of JobConfig from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # set to None if jitter_factor (nullable) is None
+        # and model_fields_set contains the field
+        if self.jitter_factor is None and "jitter_factor" in self.model_fields_set:
+            _dict['jitter_factor'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of JobConfig from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "jitter_factor": obj.get("jitter_factor"),
+            "max_retries": obj.get("max_retries"),
+            "priority": obj.get("priority"),
+            "retry_backoff": obj.get("retry_backoff"),
+            "retry_delay_secs": obj.get("retry_delay_secs"),
+            "retry_max_delay_secs": obj.get("retry_max_delay_secs"),
+            "timeout_secs": obj.get("timeout_secs")
+        })
+        return _obj
+
+

queueflow/models/job_config_request.py

@@ -0,0 +1,143 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional, Union
+from typing_extensions import Annotated
+from queueflow.models.backoff_strategy import BackoffStrategy
+from typing import Optional, Set
+from typing_extensions import Self
+
+class JobConfigRequest(BaseModel):
+    """
+    Optional per-job configuration overrides.
+    """ # noqa: E501
+    jitter_factor: Optional[Union[StrictFloat, StrictInt]] = Field(default=None, description="Retry-delay jitter in `0.0..=1.0` (e.g. `0.1` = +/-10%).")
+    max_retries: Optional[Annotated[int, Field(strict=True, ge=0)]] = None
+    priority: Optional[StrictInt] = Field(default=None, description="Higher is claimed first within a queue (ties: oldest first).")
+    queue: Optional[StrictStr] = Field(default=None, description="Override the destination queue.")
+    retry_backoff: Optional[BackoffStrategy] = Field(default=None, description="How retry delays grow between attempts (default exponential).")
+    retry_delay_secs: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Base retry delay, in seconds.")
+    retry_max_delay_secs: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Upper bound on any computed retry delay, in seconds.")
+    timeout: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Per-attempt timeout, in seconds.")
+    __properties: ClassVar[List[str]] = ["jitter_factor", "max_retries", "priority", "queue", "retry_backoff", "retry_delay_secs", "retry_max_delay_secs", "timeout"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of JobConfigRequest from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # set to None if jitter_factor (nullable) is None
+        # and model_fields_set contains the field
+        if self.jitter_factor is None and "jitter_factor" in self.model_fields_set:
+            _dict['jitter_factor'] = None
+
+        # set to None if max_retries (nullable) is None
+        # and model_fields_set contains the field
+        if self.max_retries is None and "max_retries" in self.model_fields_set:
+            _dict['max_retries'] = None
+
+        # set to None if priority (nullable) is None
+        # and model_fields_set contains the field
+        if self.priority is None and "priority" in self.model_fields_set:
+            _dict['priority'] = None
+
+        # set to None if queue (nullable) is None
+        # and model_fields_set contains the field
+        if self.queue is None and "queue" in self.model_fields_set:
+            _dict['queue'] = None
+
+        # set to None if retry_backoff (nullable) is None
+        # and model_fields_set contains the field
+        if self.retry_backoff is None and "retry_backoff" in self.model_fields_set:
+            _dict['retry_backoff'] = None
+
+        # set to None if retry_delay_secs (nullable) is None
+        # and model_fields_set contains the field
+        if self.retry_delay_secs is None and "retry_delay_secs" in self.model_fields_set:
+            _dict['retry_delay_secs'] = None
+
+        # set to None if retry_max_delay_secs (nullable) is None
+        # and model_fields_set contains the field
+        if self.retry_max_delay_secs is None and "retry_max_delay_secs" in self.model_fields_set:
+            _dict['retry_max_delay_secs'] = None
+
+        # set to None if timeout (nullable) is None
+        # and model_fields_set contains the field
+        if self.timeout is None and "timeout" in self.model_fields_set:
+            _dict['timeout'] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of JobConfigRequest from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "jitter_factor": obj.get("jitter_factor"),
+            "max_retries": obj.get("max_retries"),
+            "priority": obj.get("priority"),
+            "queue": obj.get("queue"),
+            "retry_backoff": obj.get("retry_backoff"),
+            "retry_delay_secs": obj.get("retry_delay_secs"),
+            "retry_max_delay_secs": obj.get("retry_max_delay_secs"),
+            "timeout": obj.get("timeout")
+        })
+        return _obj
+
+

queueflow/models/job_status.py

@@ -0,0 +1,41 @@
+# coding: utf-8
+
+"""
+    QueueFlow API
+
+    REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow engine.
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import json
+from enum import Enum
+from typing_extensions import Self
+
+
+class JobStatus(str, Enum):
+    """
+    Lifecycle state of a single job.
+    """
+
+    """
+    allowed enum values
+    """
+    PENDING = 'pending'
+    RUNNING = 'running'
+    COMPLETED = 'completed'
+    FAILED = 'failed'
+    RETRYING = 'retrying'
+    CANCELLED = 'cancelled'
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self:
+        """Create an instance of JobStatus from a JSON string"""
+        return cls(json.loads(json_str))
+
+