@enfyra/cloud-backup-storage 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @enfyra/cloud-backup-storage
+
+Small S3-compatible helpers for Enfyra dynamic handlers that need to stream Cloud backup objects.
+
+## Usage
+
+```js
+const backupStorage = @PKGS["@enfyra/cloud-backup-storage"];
+
+const stream = await backupStorage.createReadStream(
+  {
+    type: "Cloudflare R2",
+    accountId: settings.backup_storage_config.accountId,
+    bucket: settings.backup_storage_config.bucket,
+    accessKeyId: settings.backup_storage_config.accessKeyId,
+    secretAccessKey: settings.backup_storage_config.secretAccessKey,
+  },
+  backup.object_key,
+);
+
+return @RES.stream(stream, {
+  mimetype: backup.content_type || "application/gzip",
+  filename: `project-${project.id}-backup-${backup.id}.sql.gz`,
+});
+```
+
+`createReadStream()` returns a Node readable stream with `.pipe()`. It does not buffer the object and does not know about Enfyra routes, users, projects, or backup records.

package/index.js

@@ -0,0 +1,119 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+
+function normalizeConfig(config = {}) {
+  const provider = String(config.provider || config.type || "s3").toLowerCase();
+  const bucket = config.bucket || config.bucketName;
+  const accountId = config.accountId || config.cloudflareAccountId;
+  const accessKeyId = config.accessKeyId;
+  const secretAccessKey = config.secretAccessKey;
+  const region = config.region || (provider.includes("r2") ? "auto" : undefined);
+  const endpoint =
+    config.endpoint ||
+    (accountId ? `https://${accountId}.r2.cloudflarestorage.com` : undefined);
+
+  if (!bucket) throw new Error("bucket is required");
+  if (!accessKeyId) throw new Error("accessKeyId is required");
+  if (!secretAccessKey) throw new Error("secretAccessKey is required");
+  if (!region) throw new Error("region is required for S3-compatible storage");
+
+  return {
+    bucket,
+    region,
+    endpoint,
+    forcePathStyle:
+      typeof config.forcePathStyle === "boolean"
+        ? config.forcePathStyle
+        : Boolean(endpoint && !provider.includes("r2")),
+    credentials: {
+      accessKeyId,
+      secretAccessKey,
+    },
+  };
+}
+
+function createClient(config) {
+  const normalized = normalizeConfig(config);
+  return new S3Client({
+    region: normalized.region,
+    endpoint: normalized.endpoint,
+    forcePathStyle: normalized.forcePathStyle,
+    credentials: normalized.credentials,
+  });
+}
+
+export async function createReadStream(config, key, options = {}) {
+  if (!key) throw new Error("key is required");
+  const normalized = normalizeConfig(config);
+  const client = createClient(config);
+  const response = await client.send(
+    new GetObjectCommand({
+      Bucket: normalized.bucket,
+      Key: key,
+      Range: options.range,
+    }),
+  );
+
+  if (!response.Body || typeof response.Body.pipe !== "function") {
+    throw new Error(`Object stream is not available for key: ${key}`);
+  }
+
+  response.Body.contentLength = response.ContentLength;
+  response.Body.contentType = response.ContentType;
+  response.Body.etag = response.ETag;
+  response.Body.lastModified = response.LastModified;
+  const destroyClient = () => client.destroy();
+  response.Body.once("end", destroyClient);
+  response.Body.once("close", destroyClient);
+  response.Body.once("error", destroyClient);
+  return response.Body;
+}
+
+export async function headObject(config, key) {
+  if (!key) throw new Error("key is required");
+  const normalized = normalizeConfig(config);
+  const client = createClient(config);
+  try {
+    const response = await client.send(
+      new HeadObjectCommand({
+        Bucket: normalized.bucket,
+        Key: key,
+      }),
+    );
+
+    return {
+      contentLength: response.ContentLength,
+      contentType: response.ContentType,
+      etag: response.ETag,
+      lastModified: response.LastModified,
+    };
+  } finally {
+    client.destroy();
+  }
+}
+
+export async function deleteObject(config, key) {
+  if (!key) throw new Error("key is required");
+  const normalized = normalizeConfig(config);
+  const client = createClient(config);
+  try {
+    await client.send(
+      new DeleteObjectCommand({
+        Bucket: normalized.bucket,
+        Key: key,
+      }),
+    );
+  } finally {
+    client.destroy();
+  }
+}
+
+export default {
+  createReadStream,
+  deleteObject,
+  headObject,
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@enfyra/cloud-backup-storage",
+  "version": "0.1.0",
+  "description": "Small S3-compatible stream helpers for Enfyra Cloud backup handlers",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1024.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}