GCS

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

Quick Start

Start the server:

import { GcsServer } from "./services/gcs/src/server.js";

const server = new GcsServer(4580);
await server.start();
// ... use it ...
await server.stop();

Connect with the real Google Cloud Storage client. Point it at the fake with either apiEndpoint or the STORAGE_EMULATOR_HOST environment variable:

import { Storage } from "@google-cloud/storage";

const storage = new Storage({
  apiEndpoint: "http://127.0.0.1:4580",
  projectId: "parlel",
  // Any credentials work — the fake does not verify them.
  credentials: {
    client_email: "parlel@parlel.iam.gserviceaccount.com",
    private_key: "fake",
  },
});

const [bucket] = await storage.createBucket("my-bucket");

const file = bucket.file("hello.txt");
await file.save("hello world", { contentType: "text/plain" });

const [contents] = await file.download();
console.log(contents.toString()); // "hello world"

Or via the emulator environment variable (no apiEndpoint needed):

export STORAGE_EMULATOR_HOST=http://127.0.0.1:4580

Authentication

Google credentials and OAuth tokens are accepted but not verified (any credentials work). This matches LocalStack-style local development. Client-side operations such as getSignedUrl() still require a syntactically valid RSA private key because the signing happens in the client.

Resettable state

All state is in-memory and ephemeral. Reset it between tests:

// Programmatically
server.reset();

// Or over HTTP
await fetch("http://127.0.0.1:4580/_parlel/reset", { method: "POST" });

Implemented operations / endpoints

Service / internal

Buckets

Bucket convenience methods that route through patch/update are supported: setMetadata, setLabels, getLabels, deleteLabels, setStorageClass, setCorsConfiguration, addLifecycleRule, enableRequesterPays, setRetentionPeriod, and toggling versioning.

Objects

Object convenience methods that work on top of these: save, download (to memory or disk), createReadStream, createWriteStream, exists, getMetadata, setMetadata, copy, move, rename, makePublic, makePrivate, isPublic, setStorageClass, and ranged downloads ({ start, end }).

Uploads

Both single-shot resumable uploads (Content-Range: bytes 0-*/*) and multi-chunk resumable uploads (with chunkSize, returning 308 between chunks with a Range header) are supported.

ACLs (canned)

IAM (canned)

HMAC keys

Notifications (canned)

Feature support

Legend: ✅ fully supported · ✓ by design (intentional for a local emulator) · ⟳ on the roadmap.

Error codes & shapes

Errors are returned as the standard GCS JSON error envelope:

{
  "error": {
    "code": 404,
    "message": "No such object: my-bucket/missing.txt",
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "No such object: my-bucket/missing.txt"
      }
    ]
  }
}

Successful downloads include x-goog-hash (crc32c=...,md5=...), x-goog-generation, x-goog-metageneration, and x-goog-stored-content-length headers, mirroring the real service.

Environment variables

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.

STORAGE_EMULATOR_HOST=http://parlel-bridge:4580
GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel