Pub/Sub

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

Quick Start

Start the server:

import { PubsubServer } from "./services/pubsub/src/server.js";

const server = new PubsubServer(4582);
await server.start();
// ... use it ...
await server.stop();

Connect with the real @google-cloud/pubsub client. The fake speaks the HTTP/1.1 REST transport (the google-gax fallback mode), so the client must be constructed with fallback: true and protocol: "http". Point it at the fake via the PUBSUB_EMULATOR_HOST environment variable:

export PUBSUB_EMULATOR_HOST=127.0.0.1:4582

import { PubSub } from "@google-cloud/pubsub";

const pubsub = new PubSub({
  projectId: "parlel",
  fallback: true,       // use the HTTP/1.1 REST transport instead of gRPC
  protocol: "http",     // talk plain HTTP to the local fake
  // Any credentials work — the fake does not verify them.
  credentials: {
    client_email: "parlel@parlel.iam.gserviceaccount.com",
    private_key: "<any valid PEM>",
  },
});

// Create a topic and a subscription.
const [topic] = await pubsub.createTopic("orders");
const [subscription] = await topic.createSubscription("orders-worker");

// Publish a message.
const messageId = await topic.publishMessage({
  data: Buffer.from("hello"),
  attributes: { tier: "gold" },
});

Pulling messages

The high-level subscription.on("message", ...) streaming API uses bidi gRPC StreamingPull, which is not available over the REST transport. Use the low-level synchronous Pull RPC instead (this is exactly what the real service exposes over REST):

import { v1 } from "@google-cloud/pubsub";

const subClient = new v1.SubscriberClient({
  projectId: "parlel",
  fallback: true,
  protocol: "http",
  apiEndpoint: "127.0.0.1", // low-level gapic clients need the host explicitly
  port: 4582,
  credentials: { client_email: "parlel@parlel.iam.gserviceaccount.com", private_key: "<PEM>" },
});

const subscriptionPath = subClient.subscriptionPath("parlel", "orders-worker");

const [response] = await subClient.pull({ subscription: subscriptionPath, maxMessages: 10 });
for (const received of response.receivedMessages) {
  console.log(Buffer.from(received.message.data, "base64").toString());
  await subClient.acknowledge({ subscription: subscriptionPath, ackIds: [received.ackId] });
}

Authentication

Google credentials and OAuth tokens are accepted but not verified (any syntactically valid credentials work). No network calls leave the process.

Internal (parlel) endpoints

These are not part of Pub/Sub; they exist to manage the fake.

You can also call server.reset() directly in process.

Implemented operations / endpoints

All 35 Pub/Sub v1 RPCs plus the 3 IAM RPCs are implemented.

Publisher (topics)

Subscriber (subscriptions)

Snapshots

Schemas

IAM (google.iam.v1)

Behavior notes

• Message delivery. Publishing fans a message out to every subscription attached to the topic. Each subscription holds an in-memory backlog. Pull moves messages into an "outstanding" set keyed by ackId.
• Ack deadlines. Outstanding messages whose ack deadline has elapsed are returned to the backlog on the next Pull (lazy expiry). Acknowledge removes them permanently. ModifyAckDeadline with ackDeadlineSeconds: 0 nacks (immediate redelivery); a positive value extends the lease.
• Snapshots / Seek. CreateSnapshot captures a subscription's current unacked backlog. Seek to a snapshot restores that backlog; Seek to a time re-queues outstanding messages for redelivery.
• Dead-letter policy. When a subscription has a deadLetterPolicy, pulled messages include a deliveryAttempt counter.
• Schema revisions. CommitSchema / RollbackSchema maintain an ordered revision history; schemas can be addressed by name@revisionId.
• State is ephemeral. Everything lives in memory and is wiped on reset().

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 in the standard Google REST error envelope:

{
  "error": {
    "code": 404,
    "message": "Topic not found: projects/parlel/topics/missing",
    "status": "NOT_FOUND"
  }
}

The @google-cloud/pubsub client (over the gax REST transport) decodes the canonical gRPC status code from the HTTP status.

† The underlying service semantic is ALREADY_EXISTS (6). Over the REST fallback transport there is no HTTP status that decodes back to code 6, and HTTP 409 decodes to ABORTED — which the client's create-subscription retry policy would retry. The fake therefore surfaces create-conflicts as a non-retryable FAILED_PRECONDITION, so a duplicate create rejects immediately.

Resource naming rules

Topic / subscription / snapshot IDs must be 3–255 characters, start with a letter, contain only letters, digits, and -._~%+, and must not start with goog. These match the real Pub/Sub constraints.

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.

PUBSUB_EMULATOR_HOST=parlel-bridge:4582
PUBSUB_PROJECT_ID=parlel
GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel