Cloud Tasks

Lightweight, dependency-free fake of Google Cloud Tasks that speaks the real Cloud Tasks v2 REST API (https://cloudtasks.googleapis.com/v2), so application code using @google-cloud/tasks can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { CloudtasksServer } from "./services/cloudtasks/src/server.js";

const server = new CloudtasksServer(4584);
await server.start();
// ... use it ...
await server.stop();

Connect with the real @google-cloud/tasks client. The fake speaks the HTTP/1.1 REST transport (the google-gax fallback mode), so the low-level gapic CloudTasksClient must be constructed with fallback: true, protocol: "http", and an explicit apiEndpoint + port pointing at the fake:

import { v2 } from "@google-cloud/tasks";

const client = new v2.CloudTasksClient({
  projectId: "parlel",
  fallback: true,          // use the HTTP/1.1 REST transport instead of gRPC
  protocol: "http",        // talk plain HTTP to the local fake
  apiEndpoint: "127.0.0.1",
  port: 4584,
  // Any credentials work — the fake never verifies them.
});

const parent = client.locationPath("parlel", "us-central1");
const queueName = client.queuePath("parlel", "us-central1", "emails");

// Create a queue.
await client.createQueue({ parent, queue: { name: queueName } });

// Enqueue an HTTP target task.
const [task] = await client.createTask({
  parent: queueName,
  task: {
    httpRequest: {
      url: "https://example.com/worker",
      httpMethod: "POST",
      headers: { "Content-Type": "application/json" },
      body: Buffer.from(JSON.stringify({ id: 42 })),
    },
  },
});

// Force an immediate run (records an attempt; no real dispatch happens).
await client.runTask({ name: task.name });

Error decoding note (google-gax v5)

@google-cloud/tasks ships google-gax v5, whose REST fallback only transcodes a google.rpc.Status error body back into a canonical gRPC status code (e.g. NOT_FOUND → 5) when the transport's fetch() resolves on non-2xx responses instead of throwing. The default GoogleAuth/gaxios transporter throws, surfacing the raw HTTP status as error.code. In tests we therefore supply a tiny authClient whose fetch() always resolves the response (see tests/cloudtasks.test.ts), which makes the client surface real gRPC codes. The fake itself always returns the correct HTTP status + google.rpc.Status body — this is purely a client transport detail.

Implemented operations

The fake transcodes the Cloud Tasks v2 google.api.http annotations. Every RPC the real @google-cloud/tasks v2 client exposes is implemented.

Queues (CloudTasks service)

Tasks

IAM (google.iam.v1)

Locations mixin (google.cloud.location)

Served at the /v1/ prefix (the mixin is versioned independently of the service), matching the real client.

Internal parlel endpoints

These are not part of the Cloud Tasks API; they are conveniences for tests and tooling.

Behavior notes

• HTTP target tasks (httpRequest) and App Engine target tasks (appEngineHttpRequest) are both accepted; exactly one must be supplied.
• runTask records a synthetic successful attempt (incrementing dispatchCount / responseCount and setting firstAttempt / lastAttempt) but performs no real HTTP dispatch — zero side effects.
• Task views: FULL includes the request body; BASIC (the default) omits httpRequest.body / appEngineHttpRequest.body.
• Queue defaults: newly created queues start RUNNING with default rateLimits (500 dps / 100 burst / 1000 concurrent) and retryConfig (100 attempts, exponential backoff).
• updateQueue supports updateMask paths in snake_case, including nested leaves such as rate_limits.max_dispatches_per_second. With no mask, every supplied field is patched. It upserts if the queue does not yet exist.
• pauseQueue / resumeQueue / purgeQueue flip queue state / clear tasks. runTask on a paused or disabled queue returns FAILED_PRECONDITION.
• Pagination: pageSize + pageToken are honored for all List* RPCs (the token is an opaque base64 offset), so *Async / *Stream iterators work.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors are returned as a google.rpc.Status-shaped JSON body with the matching HTTP status code:

{
  "error": {
    "code": 404,
    "message": "Queue does not exist: projects/parlel/locations/us-central1/queues/missing",
    "status": "NOT_FOUND"
  }
}

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

CLOUD_TASKS_EMULATOR_HOST=parlel-bridge:4584
CLOUDTASKS_EMULATOR_HOST=parlel-bridge:4584
GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel