Skip to content

tasks.md

Latest commit

 

History

History
252 lines (183 loc) · 6.51 KB

tasks.md

File metadata and controls

252 lines (183 loc) · 6.51 KB

Cloud Tasks

Cloudbox emulates the Cloud Tasks REST API (v2). The google-cloud-tasks Python SDK works against it without modification.

Connection

Port: 8123 (override with CLOUDBOX_TASKS_PORT)

from google.api_core.client_options import ClientOptions
from google.auth.credentials import AnonymousCredentials
from google.cloud import tasks_v2

client = tasks_v2.CloudTasksClient(
    credentials=AnonymousCredentials(),
    client_options=ClientOptions(api_endpoint="http://localhost:8123"),
)

Queues

Create queue

POST /v2/projects/{project}/locations/{location}/queues

{
  "name": "projects/local-project/locations/us-central1/queues/my-queue",
  "rateLimits": {
    "maxDispatchesPerSecond": 500,
    "maxConcurrentDispatches": 1000,
    "maxBurstSize": 100
  },
  "retryConfig": {
    "maxAttempts": 3,
    "maxRetryDuration": "3600s",
    "minBackoff": "0.1s",
    "maxBackoff": "3600s",
    "maxDoublings": 16
  }
}

name may be omitted — a random queue ID is generated. Returns the queue resource. 409 if the queue already exists.

Get queue

GET /v2/projects/{project}/locations/{location}/queues/{queue_id}

Returns the queue resource. 404 if not found.

List queues

GET /v2/projects/{project}/locations/{location}/queues?pageSize=100&pageToken=

Returns { "queues": [...], "nextPageToken": "..." }.

Update queue

PATCH /v2/projects/{project}/locations/{location}/queues/{queue_id}

{
  "rateLimits": { "maxDispatchesPerSecond": 100 },
  "retryConfig": { "maxAttempts": 5 }
}

Merges rateLimits and retryConfig fields. Returns the updated queue resource.

Delete queue

DELETE /v2/projects/{project}/locations/{location}/queues/{queue_id}

Deletes the queue and all its tasks. Returns {}.

Pause queue

POST /v2/projects/{project}/locations/{location}/queues/{queue_id}:pause

Sets queue state to PAUSED — new task dispatches are suppressed. Returns the updated queue resource.

Resume queue

POST /v2/projects/{project}/locations/{location}/queues/{queue_id}:resume

Sets queue state back to RUNNING. Returns the updated queue resource.

Purge queue

POST /v2/projects/{project}/locations/{location}/queues/{queue_id}:purge

Deletes all tasks in the queue without deleting the queue itself. Returns the queue resource (now empty).

Tasks

Create task

POST /v2/projects/{project}/locations/{location}/queues/{queue_id}/tasks

{
  "task": {
    "name": "projects/local-project/locations/us-central1/queues/my-queue/tasks/my-task",
    "httpRequest": {
      "url": "http://localhost:8080/worker",
      "httpMethod": "POST",
      "headers": { "Content-Type": "application/json" },
      "body": "eyJrZXkiOiAidmFsdWUifQ=="
    },
    "scheduleTime": "2024-01-01T00:05:00Z"
  }
}

task.name is optional — a random task ID is generated if omitted. httpRequest.body must be base64-encoded. Returns the created task resource. 409 if a task with the same name already exists.

Get task

GET /v2/projects/{project}/locations/{location}/queues/{queue_id}/tasks/{task_id}

Returns the task resource. 404 if not found.

List tasks

GET /v2/projects/{project}/locations/{location}/queues/{queue_id}/tasks
    ?pageSize=1000&pageToken=&responseView=BASIC

responseView can be BASIC (default) or FULL. Tasks are ordered by scheduleTime. Returns { "tasks": [...], "nextPageToken": "..." }.

Delete task

DELETE /v2/projects/{project}/locations/{location}/queues/{queue_id}/tasks/{task_id}

Returns {}. 404 if not found.

Force-run task

POST /v2/projects/{project}/locations/{location}/queues/{queue_id}/tasks/{task_id}:run

Resets the task's scheduleTime to now, making it immediately eligible for dispatch. Returns the updated task resource.

Note: Cloudbox does not include a background dispatcher. Tasks are stored but not automatically dispatched to their httpRequest.url. Use :run to trigger dispatch in tests, or read the task from the queue and dispatch manually.

Task resource fields

Field Type Description
name string Full resource name
httpRequest object HTTP target configuration
pubsubTarget object Pub/Sub target configuration (publish instead of HTTP call)
scheduleTime string RFC 3339 time at which the task should be dispatched
createTime string RFC 3339 creation timestamp
dispatchCount int Number of dispatch attempts
responseCount int Number of responses received
firstAttempt object Metadata from the first dispatch attempt
lastAttempt object Metadata from the most recent dispatch attempt

HTTP request fields

Field Type Description
url string Target URL
httpMethod string POST, GET, PUT, DELETE, etc. (default: POST)
headers object HTTP headers to include
body string Base64-encoded request body
oidcToken object OIDC token configuration (stored, not enforced)
oauthToken object OAuth token configuration (stored, not enforced)

Pub/Sub target fields

Field Type Description
topicName string Full topic resource name (projects/{project}/topics/{topic})
data string Base64-encoded message payload
attributes object String key/value message attributes

When dispatched, the worker publishes the message directly to the in-process Pub/Sub store. If the topic does not exist the task is silently dropped.

Queue resource fields

Field Type Description
name string Full resource name
state string RUNNING, PAUSED, or DISABLED
rateLimits object maxDispatchesPerSecond, maxConcurrentDispatches, maxBurstSize
retryConfig object maxAttempts, maxRetryDuration, minBackoff, maxBackoff, maxDoublings

Known limitations

Feature Notes
Automatic task dispatch Tasks are not dispatched automatically; use :run or pull manually
OIDC / OAuth token injection Auth tokens accepted and stored but not attached to dispatch requests
App Engine HTTP tasks appEngineHttpRequest not implemented
Content-based deduplication Only exact name collisions are rejected — body-hash deduplication is not implemented
Rate limiting rateLimits stored and returned but not enforced

Examples

uv run python examples/tasks/enqueue.py