@max-cloud/functions 0.1.0 → 0.2.0

package/README.md

@@ -72,6 +72,32 @@ Postgres database (`DATABASE_URL`), in a table the SDK creates
   `await enqueue("mail", msg, { client: tx })`.
 - **Delay a job** with `{ delaySeconds }`.
 
+## Buckets
+
+An app's S3 buckets come from the registry:
+`mcloud apps set shop --buckets uploads,assets:public`. The maxcloud
+controller creates them in UpCloud Object Storage as `mc-<app>--<bucket>`,
+and every function gets the app's credentials as environment variables
+(the `AWS_*` ones any S3 client reads, and `MAXCLOUD_APP`). So the AWS SDK
+needs no configuration, only the bucket's full name:
+
+```ts
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { bucketName } from "@max-cloud/functions";
+
+const s3 = new S3Client({ forcePathStyle: true });
+const uploads = bucketName("uploads"); // "mc-shop--uploads"
+
+// A URL the browser uploads to directly; then enqueue the work.
+const url = await getSignedUrl(s3, new PutObjectCommand({ Bucket: uploads, Key: "a.png" }), { expiresIn: 300 });
+```
+
+A `:public` bucket's objects can be read by anyone at
+`<AWS_ENDPOINT_URL_S3>/<bucket>/<key>`; listing and writing still need the
+credentials. Object Storage has no bucket events: uploads tell the app
+themselves (presigned URL, then a queue job).
+
 ## Running
 
 The container runs `maxcloud-functions`, which starts the function named in

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { onRequest, onSchedule, onQueue, type CommonOptions, type HttpOptions, type ScheduleOptions, type QueueOptions, type HttpHandler, type HttpContext, type ScheduleHandler, type ScheduleContext, type JobHandler, type JobContext, type Job, type HttpFunction, type ScheduleFunction, type QueueFunction, } from "./define.ts";
 export { enqueue, type EnqueueOptions, type Queryable } from "./queue.ts";
+export { bucketName } from "./storage.ts";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { onRequest, onSchedule, onQueue, } from "./define.js";
 export { enqueue } from "./queue.js";
+export { bucketName } from "./storage.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,UAAU,EACV,OAAO,GAeR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAuC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,UAAU,EACV,OAAO,GAeR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAuC,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The full name of one of the app's buckets: `bucketName("uploads")` is
+ * `mc-shop--uploads` in app shop. Use it with any S3 client; the AWS SDK
+ * picks up the endpoint and credentials from the environment by itself:
+ *
+ * ```ts
+ * import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+ * const s3 = new S3Client({ forcePathStyle: true });
+ * await s3.send(new PutObjectCommand({ Bucket: bucketName("uploads"), Key: "a.txt", Body: "hi" }));
+ * ```
+ */
+export declare function bucketName(name: string, env?: Record<string, string | undefined>): string;

package/dist/storage.js

@@ -0,0 +1,28 @@
+// Buckets an app gets from the registry (`mcloud apps set <app> --buckets
+// uploads`). The maxcloud controller names them mc-<app>--<bucket> and puts
+// the app's credentials in the Secret maxcloud-s3, which every function
+// gets as environment variables: the AWS_* ones any S3 client reads
+// (endpoint, region, keys, UpCloud's checksum settings) and MAXCLOUD_APP.
+/**
+ * The full name of one of the app's buckets: `bucketName("uploads")` is
+ * `mc-shop--uploads` in app shop. Use it with any S3 client; the AWS SDK
+ * picks up the endpoint and credentials from the environment by itself:
+ *
+ * ```ts
+ * import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+ * const s3 = new S3Client({ forcePathStyle: true });
+ * await s3.send(new PutObjectCommand({ Bucket: bucketName("uploads"), Key: "a.txt", Body: "hi" }));
+ * ```
+ */
+export function bucketName(name, env = process.env) {
+    const app = env.MAXCLOUD_APP;
+    if (!app) {
+        throw new Error(`bucketName(${JSON.stringify(name)}): MAXCLOUD_APP isn't set. The app has no buckets yet ` +
+            "(mcloud apps set <app> --buckets ...), or this isn't running on maxcloud.");
+    }
+    if (!/^[a-z0-9]([a-z0-9]|-[a-z0-9])*$/.test(name)) {
+        throw new Error(`bucketName(${JSON.stringify(name)}): lowercase letters, digits and single dashes`);
+    }
+    return `mc-${app}--${name}`;
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,wEAAwE;AACxE,oEAAoE;AACpE,0EAA0E;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,GAAG,GAAuC,OAAO,CAAC,GAAG;IAC5F,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC;IAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,wDAAwD;YACxF,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,iCAAiC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,MAAM,GAAG,KAAK,IAAI,EAAE,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-cloud/functions",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Write HTTP, scheduled and queue functions for maxcloud, the homelab's run platform",
   "keywords": ["functions", "serverless", "knative", "keda"],
   "license": "MIT",