@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/file-store/gcs.ts

@@ -0,0 +1,120 @@
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { File, Storage, type UploadOptions } from '@google-cloud/storage';
+import { join } from 'path';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+export class GoogleCloudFileStore implements FileStore {
+  private readonly storage: Storage;
+
+  constructor(
+    private readonly bucketName: string,
+    private readonly basePath: string,
+    private readonly log: Logger = createLogger('stdlib:gcs-file-store'),
+  ) {
+    this.storage = new Storage();
+  }
+
+  public async checkCredentials() {
+    await this.storage.getServiceAccount();
+  }
+
+  public async save(
+    path: string,
+    data: Buffer,
+    opts: FileStoreSaveOptions = { public: false, metadata: {}, compress: false },
+  ): Promise<string> {
+    const fullPath = this.getFullPath(path);
+    try {
+      const bucket = this.storage.bucket(this.bucketName);
+      const file = bucket.file(fullPath);
+      await file.save(data, { metadata: opts.metadata, gzip: opts.compress });
+      return this.handleUploadedFile(file, opts);
+    } catch (err: any) {
+      throw new Error(`Error saving file to google cloud storage at ${fullPath}: ${err.message ?? err}`);
+    }
+  }
+
+  public async upload(
+    destPath: string,
+    srcPath: string,
+    opts: FileStoreSaveOptions = { compress: true, public: false, metadata: {} },
+  ): Promise<string> {
+    const fullPath = this.getFullPath(destPath);
+    try {
+      const bucket = this.storage.bucket(this.bucketName);
+      const file = bucket.file(fullPath);
+      const uploadOpts: UploadOptions = {
+        destination: file,
+        gzip: opts.compress,
+        metadata: opts.metadata,
+      };
+      await bucket.upload(srcPath, uploadOpts);
+      return this.handleUploadedFile(file, opts);
+    } catch (err: any) {
+      throw new Error(`Error saving file to google cloud storage at ${fullPath}: ${err.message ?? err}`);
+    }
+  }
+
+  private async handleUploadedFile(file: File, opts: { public?: boolean }): Promise<string> {
+    if (opts.public) {
+      try {
+        if (!(await file.isPublic())) {
+          await file.makePublic();
+        }
+      } catch (err: any) {
+        this.log.warn(
+          `Error making file ${file.name} public: ${
+            err.message ?? err
+          }. This is expected if we handle public access at the bucket level.`,
+        );
+      }
+      return file.publicUrl().replaceAll('%2F', '/');
+    } else {
+      return file.cloudStorageURI.toString();
+    }
+  }
+
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
+    const file = await this.getFileObject(pathOrUrlStr);
+    const contents = await file.download();
+    return contents[0];
+  }
+
+  public async download(pathOrUrlStr: string, destPath: string): Promise<void> {
+    const file = await this.getFileObject(pathOrUrlStr);
+    await file.download({ destination: destPath });
+  }
+
+  public async exists(pathOrUrlStr: string): Promise<boolean> {
+    const { bucketName, fullPath } = this.getBucketAndFullPath(pathOrUrlStr);
+    const bucket = this.storage.bucket(bucketName);
+    const file = bucket.file(fullPath);
+    const [exists] = await file.exists();
+    return exists;
+  }
+
+  private async getFileObject(pathOrUrlStr: string): Promise<File> {
+    const { bucketName, fullPath } = this.getBucketAndFullPath(pathOrUrlStr);
+    const bucket = this.storage.bucket(bucketName);
+    const file = bucket.file(fullPath);
+    if (!(await file.exists())) {
+      throw new Error(`File at ${fullPath} in gcs bucket ${bucketName} does not exist`);
+    }
+    return file;
+  }
+
+  private getBucketAndFullPath(pathOrUrlStr: string): { bucketName: string; fullPath: string } {
+    if (URL.canParse(pathOrUrlStr)) {
+      const url = new URL(pathOrUrlStr);
+      // Note that we accept reading from anywhere, not just our bucket
+      return { fullPath: url.pathname.replace(/^\/+/, ''), bucketName: url.host };
+    } else {
+      return { fullPath: this.getFullPath(pathOrUrlStr), bucketName: this.bucketName };
+    }
+  }
+
+  private getFullPath(path: string): string {
+    return this.basePath && this.basePath.length > 0 ? join(this.basePath, path) : path;
+  }
+}

package/src/file-store/http.ts

@@ -0,0 +1,88 @@
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { makeBackoff, retry } from '@aztec-labs/foundation/retry';
+import axios, { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios';
+import { createWriteStream } from 'fs';
+import { mkdir } from 'fs/promises';
+import { dirname } from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+import type { ReadOnlyFileStore } from './interface.js';
+
+/** Options for configuring HttpFileStore behavior. */
+export interface HttpFileStoreOptions {
+  /** Retry backoff intervals in seconds. Empty array disables retries. Default: [1, 1, 3]. */
+  retryBackoff?: number[];
+  /** Request timeout in milliseconds. Default: no timeout (axios default). */
+  timeoutMs?: number;
+}
+
+export class HttpFileStore implements ReadOnlyFileStore {
+  private readonly axiosInstance: AxiosInstance;
+  private readonly fetch: <T>(config: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+
+  constructor(
+    private readonly baseUrl: string,
+    private readonly log: Logger = createLogger('stdlib:http-file-store'),
+    options?: HttpFileStoreOptions,
+  ) {
+    this.axiosInstance = axios.create({
+      ...(options?.timeoutMs !== undefined && { timeout: options.timeoutMs }),
+    });
+
+    const retryBackoff = options?.retryBackoff ?? [1, 1, 3];
+    if (retryBackoff.length > 0) {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await retry(
+          () => this.axiosInstance.request<T>(config),
+          `Fetching ${config.url}`,
+          makeBackoff(retryBackoff),
+          this.log,
+          /*failSilently=*/ true,
+        );
+      };
+    } else {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await this.axiosInstance.request<T>(config);
+      };
+    }
+  }
+
+  public async read(pathOrUrl: string): Promise<Buffer> {
+    const url = this.getUrl(pathOrUrl);
+    try {
+      const response = await this.fetch<ArrayBuffer>({ url, method: 'GET', responseType: 'arraybuffer' });
+      return Buffer.from(response.data);
+    } catch (error) {
+      throw new Error(`Error fetching file from ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  public async download(pathOrUrl: string, destPath: string): Promise<void> {
+    const url = this.getUrl(pathOrUrl);
+    try {
+      this.log.debug(`Downloading file from ${url} to ${destPath}`);
+      const response = await this.fetch<Readable>({ url, method: 'GET', responseType: 'stream' });
+      this.log.debug(`Response ${response.status} (${response.statusText}) from ${url}, writing to ${destPath}`);
+      await mkdir(dirname(destPath), { recursive: true });
+      await pipeline(response.data, createWriteStream(destPath));
+      this.log.debug(`Download of ${url} to ${destPath} complete`);
+    } catch (error) {
+      throw new Error(`Error fetching file from ${url}`, { cause: error });
+    }
+  }
+
+  public async exists(pathOrUrl: string): Promise<boolean> {
+    const url = this.getUrl(pathOrUrl);
+    try {
+      await this.fetch<unknown>({ url, method: 'HEAD' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private getUrl(path: string): string {
+    return URL.canParse(path) ? path : `${this.baseUrl.replace(/\/$/, '')}/${path}`;
+  }
+}

package/src/file-store/index.ts

@@ -0,0 +1,4 @@
+export * from './interface.js';
+export * from './factory.js';
+export { type HttpFileStoreOptions } from './http.js';
+export { InMemoryFileStore } from './memory.js';

package/src/file-store/interface.ts

@@ -0,0 +1,25 @@
+/** Simple read-only file store. */
+export interface ReadOnlyFileStore {
+  /** Reads a file given a path, or an URI as returned by calling `save`. Returns file contents. */
+  read(pathOrUrl: string): Promise<Buffer>;
+  /** Downloads a file given a path, or an URI as returned by calling `save`. Saves file to local path. */
+  download(pathOrUrlStr: string, destPath: string): Promise<void>;
+  /** Returns whether a file at the given path or URI exists. */
+  exists(pathOrUrl: string): Promise<boolean>;
+}
+
+export type FileStoreSaveOptions = { public?: boolean; metadata?: Record<string, string>; compress?: boolean };
+
+/** Simple file store. */
+export interface FileStore extends ReadOnlyFileStore {
+  /**
+   * Saves contents to the given path. Returns an URI that can be used later to `read` the file.
+   * Default: `compress` is false unless explicitly set.
+   */
+  save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string>;
+  /**
+   * Uploads contents from a local file. Returns an URI that can be used later to `read` the file.
+   * Default: `compress` is true unless explicitly set to false.
+   */
+  upload(destPath: string, srcPath: string, opts?: FileStoreSaveOptions): Promise<string>;
+}

package/src/file-store/local.ts

@@ -0,0 +1,56 @@
+import { access, mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+export class LocalFileStore implements FileStore {
+  constructor(private readonly basePath: string) {}
+
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
+    const fullPath = this.getFullPath(path);
+    await mkdir(dirname(fullPath), { recursive: true });
+    const toWrite = opts?.compress ? await gzip(data) : data;
+    await writeFile(fullPath, toWrite);
+    return `file://${fullPath}`;
+  }
+
+  public async upload(destPath: string, srcPath: string, _opts: { compress: boolean }): Promise<string> {
+    const data = await readFile(srcPath);
+    return this.save(destPath, data);
+  }
+
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
+    const fullPath = this.getFullPath(pathOrUrlStr);
+    const data = await readFile(fullPath);
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
+  }
+
+  public async download(pathOrUrlStr: string, destPath: string): Promise<void> {
+    const data = await this.read(pathOrUrlStr);
+    const fullPath = this.getFullPath(destPath);
+    await writeFile(fullPath, data);
+  }
+
+  public exists(pathOrUrlStr: string): Promise<boolean> {
+    const fullPath = this.getFullPath(pathOrUrlStr);
+    return access(fullPath)
+      .then(() => true)
+      .catch(() => false);
+  }
+
+  private getFullPath(pathOrUrl: string): string {
+    if (URL.canParse(pathOrUrl)) {
+      return new URL(pathOrUrl).pathname;
+    } else {
+      return resolve(this.basePath, pathOrUrl);
+    }
+  }
+}

package/src/file-store/memory.ts

@@ -0,0 +1,94 @@
+import { writeFile } from 'fs/promises';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+// Backing data is shared per namespace so that a store created for writing and a (read-only) store
+// created later from the same `mem://` URL observe the same files — mirroring how two `file://`
+// stores over the same directory share state on disk. Without this, `FileStoreTxSource`, which
+// builds its own store from the URL, would never see what a test wrote through a different instance.
+const namespaces = new Map<string, Map<string, Buffer>>();
+
+/**
+ * In-memory {@link FileStore}, addressed via `mem://<namespace>/...`. Reads and writes are synchronous
+ * map operations with no disk I/O, so it is deterministic — useful for tests that exercise consumers
+ * of a file store (e.g. the tx file store) rather than the on-disk store itself, where a real
+ * filesystem can introduce timing flakes.
+ */
+export class InMemoryFileStore implements FileStore {
+  private readonly files: Map<string, Buffer>;
+
+  constructor(private readonly namespace: string) {
+    let files = namespaces.get(namespace);
+    if (!files) {
+      files = new Map();
+      namespaces.set(namespace, files);
+    }
+    this.files = files;
+  }
+
+  /** Clears all in-memory file store data, or a single namespace. Intended for test isolation. */
+  static clear(namespace?: string): void {
+    if (namespace === undefined) {
+      namespaces.clear();
+    } else {
+      namespaces.delete(namespace);
+    }
+  }
+
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
+    const toStore = opts?.compress ? await gzip(data) : data;
+    const key = this.key(path);
+    this.files.set(key, Buffer.from(toStore));
+    return `mem://${this.namespace}/${key}`;
+  }
+
+  public async upload(destPath: string, srcPath: string, opts?: FileStoreSaveOptions): Promise<string> {
+    const { readFile } = await import('fs/promises');
+    return this.save(destPath, await readFile(srcPath), opts);
+  }
+
+  public async read(pathOrUrl: string): Promise<Buffer> {
+    const data = this.files.get(this.key(pathOrUrl));
+    if (data === undefined) {
+      throw new Error(`File not found in memory store: ${pathOrUrl}`);
+    }
+    // Match LocalFileStore: transparently gunzip content that was stored compressed.
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
+  }
+
+  public async download(pathOrUrl: string, destPath: string): Promise<void> {
+    await writeFile(destPath, await this.read(pathOrUrl));
+  }
+
+  public exists(pathOrUrl: string): Promise<boolean> {
+    return Promise.resolve(this.files.has(this.key(pathOrUrl)));
+  }
+
+  /** Lists stored file keys, optionally restricted to those under `prefix`. Not part of {@link FileStore}. */
+  public listFiles(prefix = ''): string[] {
+    const keys = [...this.files.keys()];
+    const normalizedPrefix = prefix.replace(/^\/+/, '');
+    return normalizedPrefix ? keys.filter(k => k.startsWith(normalizedPrefix)) : keys;
+  }
+
+  /** Resolves a relative path or a `mem://` URI (as returned by `save`) to the registry key. */
+  private key(pathOrUrl: string): string {
+    const ownPrefix = `mem://${this.namespace}/`;
+    if (pathOrUrl.startsWith(ownPrefix)) {
+      return pathOrUrl.slice(ownPrefix.length);
+    }
+    if (pathOrUrl.startsWith('mem://')) {
+      // A mem:// URI for some namespace: drop the scheme and the leading namespace segment.
+      return pathOrUrl.slice('mem://'.length).replace(/^[^/]*\//, '');
+    }
+    return pathOrUrl.replace(/^\/+/, '');
+  }
+}

package/src/file-store/s3.ts

@@ -0,0 +1,258 @@
+import {
+  GetObjectCommand,
+  type GetObjectCommandOutput,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { createReadStream, createWriteStream } from 'fs';
+import { mkdir, mkdtemp, stat, unlink } from 'fs/promises';
+import { tmpdir } from 'os';
+import { basename, dirname, join } from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+import { promisify } from 'util';
+import { createGzip, gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+function normalizeBasePath(path: string): string {
+  return path?.replace(/^\/+|\/+$/g, '') ?? '';
+}
+
+export class S3FileStore implements FileStore {
+  private readonly s3: S3Client;
+  private readonly region: string;
+  private readonly endpoint?: string;
+  private readonly publicBaseUrl?: string;
+
+  constructor(
+    private readonly bucketName: string,
+    private readonly basePath: string,
+    opts: { endpoint?: string; publicBaseUrl?: string },
+    private readonly log: Logger = createLogger('stdlib:s3-file-store'),
+  ) {
+    this.endpoint = opts.endpoint;
+    this.region = this.endpoint ? 'auto' : (process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? 'us-east-1');
+    this.publicBaseUrl = opts.publicBaseUrl;
+
+    const clientOptions: any = {};
+    if (this.endpoint) {
+      clientOptions.region = 'auto';
+      clientOptions.endpoint = this.endpoint;
+      clientOptions.forcePathStyle = true;
+    } else {
+      clientOptions.region = this.region;
+    }
+    this.s3 = new S3Client(clientOptions);
+  }
+
+  public async save(path: string, data: Buffer, opts: FileStoreSaveOptions = {}): Promise<string> {
+    const key = this.getFullPath(path);
+    const shouldCompress = !!opts.compress;
+
+    const body = shouldCompress ? await gzip(data) : data;
+    const contentLength = body.length;
+    const contentType = this.detectContentType(key, shouldCompress);
+    const put = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+      ContentEncoding: shouldCompress ? 'gzip' : undefined,
+      CacheControl: opts.metadata?.['Cache-control'],
+      Metadata: this.extractUserMetadata(opts.metadata),
+      ContentLength: contentLength,
+    });
+    await this.s3.send(put);
+    return this.buildReturnedUrl(key, !!opts.public);
+  }
+
+  public async upload(destPath: string, srcPath: string, opts: FileStoreSaveOptions = {}): Promise<string> {
+    const key = this.getFullPath(destPath);
+    const shouldCompress = opts.compress !== false; // default true like GCS impl
+
+    await mkdir(dirname(srcPath), { recursive: true }).catch(() => undefined);
+    let contentLength: number | undefined;
+    let bodyPath = srcPath;
+
+    // We don't set Content-Encoding and we avoid SigV4 streaming (aws-chunked).
+    // With AWS SigV4 streaming uploads (Content-Encoding: aws-chunked[,gzip]), servers require
+    // x-amz-decoded-content-length (the size of the decoded payload) and an exact Content-Length
+    // that includes chunk metadata. For on-the-fly compression, providing
+    // those values without buffering or a pre-pass is impractical. Instead, we pre-gzip to a temp file
+    // to know ContentLength up-front and upload the gzipped bytes as-is, omitting Content-Encoding.
+    // Reference: AWS SigV4 streaming (chunked upload) requirements —
+    // https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html
+    if (shouldCompress) {
+      // Pre-gzip to a temp file so we know the exact length for R2/S3 headers
+      const tmpDir = await mkdtemp(join(tmpdir(), 's3-upload-'));
+      const gzPath = join(tmpDir, `${basename(srcPath)}.gz`);
+      try {
+        await pipeline(createReadStream(srcPath), createGzip(), createWriteStream(gzPath));
+        const st = await stat(gzPath);
+        contentLength = st.size;
+        bodyPath = gzPath;
+      } catch (err) {
+        // Ensure temp file is removed on failure
+        await unlink(gzPath).catch(() => undefined);
+        throw err;
+      }
+    } else {
+      const st = await stat(srcPath);
+      contentLength = st.size;
+      bodyPath = srcPath;
+    }
+
+    const bodyStream = createReadStream(bodyPath);
+    const contentType = this.detectContentType(key, shouldCompress);
+    try {
+      const put = new PutObjectCommand({
+        Bucket: this.bucketName,
+        Key: key,
+        Body: bodyStream as any,
+        ContentType: contentType,
+        CacheControl: opts.metadata?.['Cache-control'],
+        Metadata: this.extractUserMetadata(opts.metadata),
+        // Explicitly set ContentLength so R2 can compute x-amz-decoded-content-length correctly
+        ContentLength: contentLength,
+      } as any);
+      await this.s3.send(put);
+    } finally {
+      if (shouldCompress && bodyPath !== srcPath) {
+        await unlink(bodyPath).catch(() => undefined);
+      }
+    }
+    return this.buildReturnedUrl(key, !!opts.public);
+  }
+
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
+    const { bucket, key } = this.getBucketAndKey(pathOrUrlStr);
+    const out: GetObjectCommandOutput = await this.s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    const stream = out.Body as Readable;
+    const chunks: Buffer[] = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const buffer = Buffer.concat(chunks);
+    if (out.ContentEncoding === 'gzip') {
+      return await gunzip(buffer);
+    }
+    return buffer;
+  }
+
+  public async download(pathOrUrlStr: string, destPath: string): Promise<void> {
+    const { bucket, key } = this.getBucketAndKey(pathOrUrlStr);
+    const out: GetObjectCommandOutput = await this.s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    await mkdir(dirname(destPath), { recursive: true });
+    await pipeline(out.Body as Readable, createWriteStream(destPath));
+  }
+
+  public async exists(pathOrUrlStr: string): Promise<boolean> {
+    try {
+      const { bucket, key } = this.getBucketAndKey(pathOrUrlStr);
+      await this.s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+      return true;
+    } catch (err: any) {
+      const code = err?.$metadata?.httpStatusCode ?? err?.name ?? err?.Code;
+      if (code === 404 || code === 'NotFound' || code === 'NoSuchKey') {
+        return false;
+      }
+      this.log.warn(`Error checking existence for ${pathOrUrlStr}: ${err?.message ?? String(err)}`);
+      return false;
+    }
+  }
+
+  private extractUserMetadata(meta?: Record<string, string>): Record<string, string> | undefined {
+    if (!meta) {
+      return undefined;
+    }
+    const { ['Cache-control']: _ignored, ...rest } = meta;
+    return Object.keys(rest).length ? rest : undefined;
+  }
+
+  private detectContentType(key: string, isCompressed: boolean | undefined): string | undefined {
+    // Basic content type inference
+    const lower = key.toLowerCase();
+    if (lower.endsWith('.json') || lower.endsWith('.json.gz')) {
+      return 'application/json';
+    }
+    if (lower.endsWith('.txt') || lower.endsWith('.log') || lower.endsWith('.csv') || lower.endsWith('.md')) {
+      return 'text/plain; charset=utf-8';
+    }
+    if (lower.endsWith('.db') || lower.endsWith('.sqlite') || lower.endsWith('.bin')) {
+      return 'application/octet-stream';
+    }
+    if (lower.endsWith('.wasm') || lower.endsWith('.wasm.gz')) {
+      return 'application/wasm';
+    }
+    // If compressed, prefer octet-stream unless known
+    if (isCompressed) {
+      return 'application/octet-stream';
+    }
+    return undefined;
+  }
+
+  private buildReturnedUrl(key: string, makePublic: boolean): string {
+    if (!makePublic) {
+      return `s3://${this.bucketName}/${key}`;
+    }
+
+    if (this.publicBaseUrl) {
+      const base = this.publicBaseUrl.replace(/\/$/, '');
+      // key already includes basePath via getFullPath, so do not prefix basePath again
+      const full = key.replace(/^\/+/, '');
+      return `${base}/${full}`;
+    }
+
+    // Try to synthesize a URL from endpoint if available (works for public R2 buckets)
+    if (this.endpoint) {
+      try {
+        const url = new URL(this.endpoint);
+        return `https://${this.bucketName}.${url.host}/${key}`;
+      } catch {
+        // fallthrough
+      }
+    }
+
+    // Fallback to AWS style URL if region looks valid
+    return `https://${this.bucketName}.s3.${this.region}.amazonaws.com/${key}`;
+  }
+
+  private getBucketAndKey(pathOrUrlStr: string): { bucket: string; key: string } {
+    if (URL.canParse(pathOrUrlStr)) {
+      const url = new URL(pathOrUrlStr);
+      if (url.protocol === 's3:') {
+        return { bucket: url.host, key: url.pathname.replace(/^\/+/, '') };
+      }
+      // For https URLs, try to infer virtual-hosted or path-style
+      if (url.protocol === 'https:' || url.protocol === 'http:') {
+        // If the URL matches the configured publicBaseUrl host, map back to our bucket and key
+        if (this.publicBaseUrl && url.host === new URL(this.publicBaseUrl).host) {
+          return { bucket: this.bucketName, key: url.pathname.replace(/^\/+/, '') };
+        }
+        const hostParts = url.host.split('.');
+        if (hostParts.length > 3 && (hostParts[1] === 's3' || hostParts[hostParts.length - 2] === 'r2')) {
+          // virtual hosted
+          return { bucket: hostParts[0], key: url.pathname.replace(/^\/+/, '') };
+        } else if (this.endpoint && url.host === new URL(this.endpoint).host) {
+          // path-style at custom endpoint
+          const [bucket, ...rest] = url.pathname.replace(/^\/+/, '').split('/');
+          return { bucket, key: rest.join('/') };
+        }
+      }
+    }
+    // Treat as path
+    return { bucket: this.bucketName, key: this.getFullPath(pathOrUrlStr) };
+  }
+
+  private getFullPath(path: string): string {
+    const base = normalizeBasePath(this.basePath);
+    const rel = path.replace(/^\/+/, '');
+    return base ? join(base, rel) : rel;
+  }
+}