django-database-task 0.1.0__tar.gz → 0.2.1__tar.gz

{django_database_task-0.1.0/django_database_task.egg-info → django_database_task-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-database-task
-Version: 0.1.0
+Version: 0.2.1
 Summary: A database-backed task queue backend for Django 6.0's built-in task framework
 Author-email: Shinya Okano <tokibito@gmail.com>
 Maintainer-email: Shinya Okano <tokibito@gmail.com>
@@ -25,6 +25,9 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Django>=6.0
+Provides-Extra: cloudtasks
+Requires-Dist: google-cloud-tasks>=2.0.0; extra == "cloudtasks"
+Requires-Dist: google-auth>=2.0.0; extra == "cloudtasks"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-django>=4.5; extra == "dev"
@@ -43,6 +46,7 @@ A database-backed task queue backend for Django 6.0's built-in task framework.
 - **Exclusive locking** - Prevents duplicate task execution with `SELECT FOR UPDATE SKIP LOCKED`
 - **Django Admin integration** - View and manage tasks from the admin interface
 - **Async support** - Supports async task functions
+- **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
 
@@ -291,7 +295,12 @@ python manage.py purge_completed_database_tasks [options]
 You can also process tasks programmatically without management commands:
 
 ```python
-from django_database_task import process_one_task, process_tasks, get_pending_task_count
+from django_database_task import (
+    process_one_task,
+    process_tasks,
+    get_pending_task_count,
+    run_task_by_id,
+)
 
 # Process a single task
 result = process_one_task()
@@ -308,6 +317,14 @@ results = process_tasks(queue_name="emails", max_tasks=5)
 # Get pending task count
 count = get_pending_task_count()
 print(f"Pending tasks: {count}")
+
+# Execute a specific task by ID
+result = run_task_by_id("550e8400-e29b-41d4-a716-446655440000")
+if result:
+    print(f"Executed: {result.id}, status: {result.status}")
+
+# Retry a failed task
+result = run_task_by_id("...", allow_retry=True)
 ```
 
 ## HTTP Endpoints (Optional)
@@ -335,6 +352,8 @@ urlpatterns = [
 | `/tasks/run/` | POST | Process multiple pending tasks |
 | `/tasks/run-one/` | POST | Process a single pending task |
 | `/tasks/status/` | GET | Get pending task count |
+| `/tasks/execute/<uuid>/` | POST | Execute a specific task by ID |
+| `/tasks/purge/` | POST | Delete completed tasks |
 
 ### Request Parameters
 
@@ -385,6 +404,52 @@ Response:
 {"pending_count": 5}
 ```
 
+#### POST `/tasks/execute/<uuid>/`
+
+Execute a specific task by ID. This endpoint is designed for external trigger systems
+(e.g., Cloud Tasks, webhooks) that need to execute a specific task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `fail_on_error` | query string | "false" | Return HTTP 500 on task failure |
+| `allow_retry` | query string | "false" | Allow re-execution of FAILED tasks |
+
+Response (success):
+```json
+{"executed": true, "result": {"id": "uuid", "status": "SUCCESSFUL", "task_path": "..."}}
+```
+
+Response (task not in executable status):
+```json
+{"executed": false, "reason": "Task is not in READY status"}
+```
+
+Response (task not found):
+```json
+{"error": "Task not found"}  // HTTP 404
+```
+
+#### POST `/tasks/purge/`
+
+Delete completed tasks from the database. Useful for cron-based cleanup.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
+| `status` | string | "SUCCESSFUL,FAILED" | Target statuses, comma-separated |
+| `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
+| `dry_run` | bool | false | If true, return count without deleting |
+
+Response:
+```json
+{"deleted": 150, "dry_run": false}
+```
+
+Response (dry run):
+```json
+{"count": 150, "dry_run": true}
+```
+
 ### Example Usage
 
 ```bash
@@ -400,6 +465,16 @@ curl -X POST http://localhost:8000/tasks/run/ \
 
 # Get pending task count
 curl http://localhost:8000/tasks/status/
+
+# Delete tasks completed more than 7 days ago
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 7}'
+
+# Dry run to check how many tasks would be deleted
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30, "dry_run": true}'
 ```
 
 ### Use Cases
@@ -446,13 +521,31 @@ if [ "$count" -gt 100 ]; then
 fi
 ```
 
+#### Scheduled Cleanup
+
+Use cron or Cloud Scheduler to delete old completed tasks:
+
+```bash
+# Daily cleanup via cron or Cloud Scheduler
+# Delete tasks completed more than 30 days ago
+curl -X POST https://your-app.com/tasks/purge/ \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30}'
+```
+
 ### Security
 
 The endpoints are CSRF-exempt for API/webhook use. **Always add authentication in production:**
 
 ```python
 from django.contrib.admin.views.decorators import staff_member_required
-from django_database_task.views import RunTasksView, RunOneTaskView, TaskStatusView
+from django_database_task.views import (
+    RunTasksView,
+    RunOneTaskView,
+    TaskStatusView,
+    PurgeCompletedTasksView,
+)
 
 urlpatterns = [
     path(
@@ -470,6 +563,11 @@ urlpatterns = [
         staff_member_required(TaskStatusView.as_view()),
         name="task_status",
     ),
+    path(
+        "tasks/purge/",
+        staff_member_required(PurgeCompletedTasksView.as_view()),
+        name="purge_completed_tasks",
+    ),
 ]
 ```
 
@@ -492,15 +590,204 @@ urlpatterns = [
 ]
 ```
 
+## Google Cloud Tasks Integration
+
+For serverless environments like Google App Engine or Cloud Run, you can use the Cloud Tasks backend to automatically create Cloud Tasks when tasks are enqueued.
+
+### Installation
+
+```bash
+pip install django-database-task[cloudtasks]
+```
+
+### Quick Setup
+
+```python
+# settings.py
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "QUEUES": [],  # Allow all queue names
+    },
+}
+```
+
+Project ID, location, and handler URL are auto-detected from GAE/Cloud Run environment.
+
+**Important**: Set `QUEUES: []` to allow any queue name, or list the queues you use:
+```python
+"QUEUES": ["default", "emails", "batch"],  # Only these queues allowed
+```
+
+The Cloud Tasks queue name is determined by the task's `queue_name` attribute:
+
+```python
+@task  # Uses "default" queue
+def normal_task():
+    pass
+
+@task(queue="batch")  # Uses "batch" queue
+def batch_task():
+    pass
+
+@task(queue="high-priority")  # Uses "high-priority" queue
+def urgent_task():
+    pass
+```
+
+This allows you to configure different rate limits and concurrency settings per queue in Cloud Tasks.
+
+### How It Works
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Backend as CloudTasksDatabaseBackend
+    participant DB as Database
+    participant CT as Cloud Tasks
+    participant Handler as /tasks/execute/
+
+    Note over App,Handler: Task Enqueue
+    App->>Backend: task.enqueue(args, kwargs)
+    Backend->>DB: INSERT task (status=READY)
+    DB-->>Backend: Task ID
+    Backend->>CT: Create Cloud Task (task_id only)
+    CT-->>Backend: OK
+    Backend-->>App: TaskResult (id, status=READY)
+
+    Note over App,Handler: Task Execution (triggered by Cloud Tasks)
+    CT->>Handler: POST /tasks/execute/<task_id>/<br/>(with OIDC token if configured)
+    Handler->>Handler: Verify OIDC token (optional)
+    Handler->>DB: SELECT task by ID
+    DB-->>Handler: Task record
+    Handler->>DB: UPDATE status=RUNNING
+    Handler->>Handler: Execute task function
+    alt Success
+        Handler->>DB: UPDATE status=SUCCESSFUL
+        Handler-->>CT: HTTP 200
+    else Failure
+        Handler->>DB: UPDATE status=FAILED
+        Handler-->>CT: HTTP 500 (triggers retry)
+    end
+```
+
+The Cloud Task only contains the task ID. All task parameters are stored in the database, ensuring:
+- **Blue/Green deployment support**: Tasks execute on the same version that enqueued them
+- **Database as source of truth**: Task parameters are never lost
+- **Automatic retry**: Cloud Tasks handles retry with the task ID
+
+### Configuration Options
+
+```python
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            # All settings are optional - auto-detected from environment
+
+            # Override auto-detection if needed
+            # "CLOUD_TASKS_PROJECT": "my-project",
+            # "CLOUD_TASKS_LOCATION": "asia-northeast1",
+            # "TASK_HANDLER_URL": "https://myapp.example.com/tasks/execute/{task_id}/",
+            # "TASK_HANDLER_PATH": "/tasks/execute/{task_id}/",
+
+            # OIDC authentication (optional)
+            # "OIDC_SERVICE_ACCOUNT_EMAIL": "...",
+            # "OIDC_AUDIENCE": "https://...",
+        },
+    },
+}
+```
+
+### Auto-Detection
+
+| Setting | Detection Method | Description |
+|---------|------------------|-------------|
+| Project | `GOOGLE_CLOUD_PROJECT` env var | GCP project ID |
+| Location | `CLOUD_RUN_REGION` env var, or metadata server | Cloud Tasks region |
+| Handler URL | Built from `K_SERVICE`, `GAE_SERVICE`, `GAE_VERSION` | Task execution endpoint |
+| Queue name | Task's `queue_name` attribute | Defaults to "default" |
+
+### OIDC Authentication
+
+When `OIDC_SERVICE_ACCOUNT_EMAIL` is configured, Cloud Tasks will send OIDC tokens with each request. The backend automatically verifies these tokens on the `/tasks/execute/` and `/tasks/purge/` endpoints.
+
+```python
+# settings.py - Automatic OIDC verification
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "QUEUES": [],  # Allow all queue names
+        "OPTIONS": {
+            "OIDC_SERVICE_ACCOUNT_EMAIL": "my-sa@project.iam.gserviceaccount.com",
+            # OIDC_AUDIENCE is auto-detected from handler URL if not set
+        },
+    },
+}
+```
+
+Alternatively, you can use the decorator directly on your URL configuration:
+
+```python
+# urls.py
+from django.urls import path
+from django_database_task.views import ExecuteTaskView
+from django_database_task.cloudtasks import verify_cloud_tasks_oidc
+
+urlpatterns = [
+    path(
+        "tasks/execute/<uuid:task_id>/",
+        verify_cloud_tasks_oidc(
+            ExecuteTaskView.as_view(),
+            audience="https://myapp.example.com"
+        ),
+        name="execute_task",
+    ),
+]
+```
+
+### Detection Utilities
+
+You can use the detection functions directly:
+
+```python
+from django_database_task.cloudtasks import (
+    detect_gcp_project,
+    detect_gcp_location,
+    detect_task_handler_host,
+    is_cloud_run,
+    is_app_engine,
+)
+
+if is_cloud_run():
+    print(f"Running on Cloud Run in {detect_gcp_location()}")
+elif is_app_engine():
+    print(f"Running on App Engine in project {detect_gcp_project()}")
+```
+
 ## Django Admin
 
-The package includes a Django Admin integration to view task status:
+The package includes a Django Admin integration to view and manage tasks:
 
 - Task list with status badges
 - Filter by status, queue, backend
 - Search by task ID or path
 - View task arguments and results
 
+### Admin Actions
+
+The admin interface provides the following bulk actions:
+
+| Action | Description |
+|--------|-------------|
+| **Run selected tasks** | Execute selected tasks that are in READY status |
+| **Retry failed tasks** | Reset FAILED tasks to READY status and re-execute them |
+
+These actions are useful for:
+- Manually triggering task execution from the admin
+- Retrying failed tasks after fixing issues
+- Testing task execution during development
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.