@max-cloud/functions 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxemilian Grönblom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @max-cloud/functions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write functions for maxcloud, the homelab's run platform (Knative and KEDA,
+see [maxemiliang/maxcloud](https://github.com/maxemiliang/maxcloud)). Export
+them from your app's entry module, and each one is deployed on its own:
+
+```ts
+import { enqueue, onQueue, onRequest, onSchedule } from "@max-cloud/functions";
+
+// A Knative service: scales to zero, starts on the first request.
+export const api = onRequest({ public: true }, async (req) => {
+  const { key } = await req.json();
+  await enqueue("images", { key });
+  return Response.json({ queued: key }, { status: 202 });
+});
+
+// A CronJob.
+export const nightly = onSchedule("0 3 * * *", async () => {
+  // ...
+});
+
+// A worker that KEDA starts when the queue has jobs, and stops when it's empty.
+export const resize = onQueue<{ key: string }>("images", async (job) => {
+  console.log("resizing", job.payload.key, "attempt", job.attempt);
+});
+```
+
+The export's name becomes the function's: `resizeImage` is deployed as
+`resize-image`.
+
+## HTTP functions
+
+`onRequest(handler)` or `onRequest(options, handler)`. The handler takes a
+standard `Request` and returns a `Response`, so fetch-style frameworks work
+as they are: `onRequest(app.fetch)` with Hono, for example.
+
+| Option | Default | |
+| --- | --- | --- |
+| `public` | `false` | Reachable from the internet at `https://<name>-<app>.gronblom.dev`. Otherwise cluster-local. |
+| `minInstances` | `0` | Instances kept running when idle. |
+| `maxInstances` | `3` | |
+| `concurrency` | `0` | Requests one instance handles before another starts (0: no limit). |
+| `timeoutSeconds` | `300` | Per request. |
+
+## Scheduled functions
+
+`onSchedule("0 3 * * *", handler)`, or `onSchedule(options, handler)` with
+`schedule`, `timeZone` (default UTC), `retries` (default 0) and
+`timeoutSeconds` (default 3600). A run that throws exits 1, and Kubernetes
+retries it `retries` times.
+
+## Queues
+
+`onQueue(queue, handler)` or `onQueue(options, handler)`. `enqueue(queue,
+payload)` adds a job from anywhere in the app. Jobs live in the app's
+Postgres database (`DATABASE_URL`), in a table the SDK creates
+(`maxcloud_jobs`).
+
+| Option | Default | |
+| --- | --- | --- |
+| `concurrency` | `1` | Jobs one instance works on at once. |
+| `maxInstances` | `3` | |
+| `maxAttempts` | `5` | Tries before a job is marked `failed`. |
+| `backoffSeconds` | `10` | Delay before the first retry, doubled each time. |
+| `timeoutSeconds` | `300` | Per job. A job past it is aborted and retried. |
+
+- **Retries:** a job that throws is retried, and so is one whose worker
+  died, once its lease runs out. A job can run more than once, so make
+  handlers safe to repeat.
+- **Enqueue in your own transaction:** pass `{ client }`, and the job exists
+  only if your transaction commits:
+  `await enqueue("mail", msg, { client: tx })`.
+- **Delay a job** with `{ delaySeconds }`.
+
+## Running
+
+The container runs `maxcloud-functions`, which starts the function named in
+`FUNCTION_TARGET`:
+
+- **HTTP:** a server on `$PORT`.
+- **Schedule:** one run, then it exits.
+- **Queue:** the worker loop.
+
+On SIGTERM it finishes what's in flight and exits 0, so pods don't end in
+`Error`. Your app's `package.json` needs:
+
+```json
+{
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": { "start": "maxcloud-functions" }
+}
+```
+
+To try a function locally:
+
+```fish
+FUNCTION_TARGET=api npx maxcloud-functions
+```
+
+`maxcloud-functions --describe` prints the app's functions and their
+settings as JSON; `mcloud` deploys from that. While it runs,
+`MAXCLOUD_DESCRIBE=1` is set, so module-level code can skip connecting to
+things.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// maxcloud-functions: the container's entrypoint.
+//
+//   maxcloud-functions                 run $FUNCTION_TARGET
+//   maxcloud-functions --target hello  run that function
+//   maxcloud-functions --describe      print the app's functions as JSON
+//   MAXCLOUD_DESCRIBE=1 maxcloud-functions   the same, as one tagged line
+import { parseArgs } from "node:util";
+import { DESCRIBE_TAG, describe, load, run, sourcePath } from "./runtime.js";
+const usage = `usage: maxcloud-functions [--target NAME] [--source FILE] [--port N]
+       maxcloud-functions --describe [--source FILE]
+
+Runs one of the app's functions: the HTTP server, a scheduled run, or a queue
+worker. NAME defaults to $FUNCTION_TARGET, FILE to package.json's "main", the
+port to $PORT or 8080.`;
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            target: { type: "string" },
+            source: { type: "string" },
+            port: { type: "string" },
+            describe: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        console.log(usage);
+        return 0;
+    }
+    // MAXCLOUD_DESCRIBE=1 in the environment does the same as --describe,
+    // as one tagged line: that's how the deploy workflow asks a built image,
+    // whatever its start command, and other output around it doesn't matter.
+    const fromEnv = !values.describe && process.env.MAXCLOUD_DESCRIBE === "1";
+    if (values.describe)
+        process.env.MAXCLOUD_DESCRIBE = "1";
+    const found = await load(sourcePath(values.source));
+    if (values.describe) {
+        process.stdout.write(JSON.stringify(describe(found), null, 2) + "\n");
+        return 0;
+    }
+    if (fromEnv) {
+        process.stdout.write(DESCRIBE_TAG + JSON.stringify(describe(found)) + "\n");
+        return 0;
+    }
+    const names = found.map((f) => f.name).join(", ") || "none";
+    const target = values.target ?? process.env.FUNCTION_TARGET;
+    if (!target) {
+        console.error(`maxcloud-functions: which function? Set FUNCTION_TARGET or --target (${names})`);
+        return 2;
+    }
+    const f = found.find((x) => x.name === target || x.exportName === target);
+    if (!f) {
+        console.error(`maxcloud-functions: no function ${target} (found: ${names})`);
+        return 2;
+    }
+    // SIGTERM is how Kubernetes stops a pod; finish cleanly and exit 0.
+    const stop = new AbortController();
+    for (const sig of ["SIGTERM", "SIGINT"]) {
+        process.once(sig, () => stop.abort(new Error(`${sig} received`)));
+    }
+    const port = Number(values.port ?? process.env.PORT ?? 8080);
+    return run(f, { port, signal: stop.signal });
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error("maxcloud-functions:", err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/define.d.ts

@@ -0,0 +1,124 @@
+/** Marks an export as a maxcloud function. */
+export declare const FUNCTION: unique symbol;
+/** Resources and limits every kind of function takes. */
+export interface CommonOptions {
+    /** Memory the container requests and is limited to, e.g. "256Mi". */
+    memory?: string;
+    /** CPU the container requests, e.g. "100m". */
+    cpu?: string;
+    /**
+     * How long one invocation may run. HTTP: per request (default 300).
+     * Schedule: the whole run (default 3600). Queue: per job (default 300).
+     */
+    timeoutSeconds?: number;
+}
+export interface HttpOptions extends CommonOptions {
+    /** Reachable from the internet at https://<name>-<app>.gronblom.dev. Default false: cluster-local only. */
+    public?: boolean;
+    /** Instances kept running when idle. Default 0 (scale to zero). */
+    minInstances?: number;
+    /** Most instances at once. Default 3. */
+    maxInstances?: number;
+    /** Requests one instance handles at once before another starts. Default 0 (no limit; Knative scales on 100 in flight). */
+    concurrency?: number;
+}
+export interface ScheduleOptions extends CommonOptions {
+    /** Cron schedule, e.g. "0 3 * * *". */
+    schedule: string;
+    /** IANA time zone for the schedule. Default UTC. */
+    timeZone?: string;
+    /** Times a failed run is retried. Default 0. */
+    retries?: number;
+}
+export interface QueueOptions extends CommonOptions {
+    /** Queue name: lowercase letters, digits, dashes and underscores. */
+    queue: string;
+    /** Jobs one instance works on at once. Default 1. */
+    concurrency?: number;
+    /** Most instances at once. Default 3. */
+    maxInstances?: number;
+    /** Tries before a job is marked failed. Default 5. */
+    maxAttempts?: number;
+    /** Delay before the first retry, doubled for each later one. Default 10. */
+    backoffSeconds?: number;
+}
+export interface HttpContext {
+    /** Aborted when the client goes away or the server shuts down. */
+    signal: AbortSignal;
+}
+export type HttpHandler = (request: Request, context: HttpContext) => Response | Promise<Response>;
+export interface ScheduleContext {
+    /** Aborted at the timeout, or when the run is stopped. */
+    signal: AbortSignal;
+    /** When this run started. */
+    startedAt: Date;
+}
+export type ScheduleHandler = (context: ScheduleContext) => void | Promise<void>;
+export interface Job<T> {
+    id: string;
+    queue: string;
+    payload: T;
+    /** 1 on the first try. */
+    attempt: number;
+    createdAt: Date;
+}
+export interface JobContext {
+    /** Aborted at the timeout, or when the worker shuts down. */
+    signal: AbortSignal;
+}
+export type JobHandler<T> = (job: Job<T>, context: JobContext) => void | Promise<void>;
+export interface HttpFunction {
+    readonly [FUNCTION]: true;
+    readonly kind: "http";
+    readonly options: HttpOptions;
+    readonly handler: HttpHandler;
+    /** Calls the handler directly, e.g. in tests. */
+    fetch(request: Request): Promise<Response>;
+}
+export interface ScheduleFunction {
+    readonly [FUNCTION]: true;
+    readonly kind: "schedule";
+    readonly options: ScheduleOptions;
+    readonly handler: ScheduleHandler;
+}
+export interface QueueFunction<T = unknown> {
+    readonly [FUNCTION]: true;
+    readonly kind: "queue";
+    readonly options: QueueOptions;
+    readonly handler: JobHandler<T>;
+}
+export type MaxcloudFunction = HttpFunction | ScheduleFunction | QueueFunction<any>;
+export declare function isFunction(v: unknown): v is MaxcloudFunction;
+/**
+ * An HTTP function: a Knative service that scales to zero.
+ *
+ * ```ts
+ * export const hello = onRequest(async (req) => new Response("hi"));
+ * export const api = onRequest({ public: true }, app.fetch); // e.g. a Hono app
+ * ```
+ */
+export declare function onRequest(handler: HttpHandler): HttpFunction;
+export declare function onRequest(options: HttpOptions, handler: HttpHandler): HttpFunction;
+/**
+ * A scheduled function: a Kubernetes CronJob that runs it once per tick.
+ *
+ * ```ts
+ * export const nightly = onSchedule("0 3 * * *", async () => { ... });
+ * ```
+ */
+export declare function onSchedule(schedule: string, handler: ScheduleHandler): ScheduleFunction;
+export declare function onSchedule(options: ScheduleOptions, handler: ScheduleHandler): ScheduleFunction;
+export declare function checkQueueName(queue: string): void;
+/**
+ * A queue function: a worker that KEDA starts when the queue has jobs, and
+ * scales to zero when it's empty. Add jobs with `enqueue`.
+ *
+ * ```ts
+ * export const resize = onQueue<{ key: string }>("images", async (job) => { ... });
+ * ```
+ *
+ * A job that throws is retried with backoff; one still running when its
+ * timeout passes is aborted and retried too. Make handlers safe to run twice.
+ */
+export declare function onQueue<T = unknown>(queue: string, handler: JobHandler<T>): QueueFunction<T>;
+export declare function onQueue<T = unknown>(options: QueueOptions, handler: JobHandler<T>): QueueFunction<T>;

package/dist/define.js

@@ -0,0 +1,45 @@
+// Defining functions: onRequest, onSchedule, onQueue. Each returns a plain
+// object that the runtime recognises among the module's exports; nothing runs
+// until the runtime picks one with FUNCTION_TARGET.
+/** Marks an export as a maxcloud function. */
+export const FUNCTION = Symbol.for("maxcloud.function");
+export function isFunction(v) {
+    return typeof v === "object" && v !== null && FUNCTION in v;
+}
+export function onRequest(a, b) {
+    const [options, handler] = typeof a === "function" ? [{}, a] : [a, b];
+    if (typeof handler !== "function")
+        throw new TypeError("onRequest: missing handler");
+    return {
+        [FUNCTION]: true,
+        kind: "http",
+        options,
+        handler,
+        async fetch(request) {
+            return handler(request, { signal: request.signal });
+        },
+    };
+}
+export function onSchedule(a, handler) {
+    const options = typeof a === "string" ? { schedule: a } : a;
+    if (!options.schedule || options.schedule.trim().split(/\s+/).length !== 5) {
+        throw new TypeError(`onSchedule: ${JSON.stringify(options.schedule)} isn't a five-field cron schedule`);
+    }
+    if (typeof handler !== "function")
+        throw new TypeError("onSchedule: missing handler");
+    return { [FUNCTION]: true, kind: "schedule", options, handler };
+}
+const QUEUE_NAME = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+export function checkQueueName(queue) {
+    if (!QUEUE_NAME.test(queue)) {
+        throw new TypeError(`queue name ${JSON.stringify(queue)}: use lowercase letters, digits, dashes and underscores`);
+    }
+}
+export function onQueue(a, handler) {
+    const options = typeof a === "string" ? { queue: a } : a;
+    checkQueueName(options.queue);
+    if (typeof handler !== "function")
+        throw new TypeError("onQueue: missing handler");
+    return { [FUNCTION]: true, kind: "queue", options, handler };
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,oDAAoD;AAEpD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAyGxD,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,QAAQ,IAAI,CAAC,CAAC;AAC9D,CAAC;AAYD,MAAM,UAAU,SAAS,CAAC,CAA4B,EAAE,CAAe;IACrE,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACrF,OAAO;QACL,CAAC,QAAQ,CAAC,EAAE,IAAI;QAChB,IAAI,EAAE,MAAM;QACZ,OAAO;QACP,OAAO;QACP,KAAK,CAAC,KAAK,CAAC,OAAO;YACjB,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAWD,MAAM,UAAU,UAAU,CAAC,CAA2B,EAAE,OAAwB;IAC9E,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,SAAS,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,6BAA6B,CAAC,CAAC;IACtF,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,GAAG,4BAA4B,CAAC;AAEhD,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACpH,CAAC;AACH,CAAC;AAeD,MAAM,UAAU,OAAO,CAAc,CAAwB,EAAE,OAAsB;IACnF,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC;IACnF,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/D,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,10 @@
+import { type Server } from "node:http";
+import type { HttpFunction } from "./define.ts";
+export interface Serving {
+    server: Server;
+    /** The port it listens on (useful with port 0). */
+    port: number;
+    /** Stops accepting requests and resolves once those in flight have finished, or `graceMs` passed. */
+    close(graceMs?: number): Promise<void>;
+}
+export declare function serveHttp(fn: HttpFunction, port: number, log?: (msg: string) => void): Promise<Serving>;

package/dist/http.js

@@ -0,0 +1,106 @@
+// Serving an HTTP function: Node's http server in front of a fetch-style
+// handler (Request in, Response out).
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+function toRequest(req, signal) {
+    // Traefik and Knative's queue-proxy set these for the original request.
+    const proto = String(req.headers["x-forwarded-proto"] ?? "http").split(",")[0].trim();
+    const host = req.headers["x-forwarded-host"] ?? req.headers.host ?? "localhost";
+    const url = new URL(req.url ?? "/", `${proto}://${host}`);
+    const headers = new Headers();
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        headers.append(req.rawHeaders[i], req.rawHeaders[i + 1]);
+    }
+    const method = req.method ?? "GET";
+    const hasBody = method !== "GET" && method !== "HEAD";
+    return new Request(url, {
+        method,
+        headers,
+        body: hasBody ? Readable.toWeb(req) : undefined,
+        signal,
+        // Node needs this for a streamed request body.
+        duplex: hasBody ? "half" : undefined,
+    });
+}
+async function writeResponse(res, response, head) {
+    res.statusCode = response.status;
+    if (response.statusText)
+        res.statusMessage = response.statusText;
+    const cookies = response.headers.getSetCookie();
+    response.headers.forEach((value, key) => {
+        if (key !== "set-cookie")
+            res.setHeader(key, value);
+    });
+    if (cookies.length)
+        res.setHeader("set-cookie", cookies);
+    if (!response.body || head) {
+        res.end();
+        return;
+    }
+    await pipeline(Readable.fromWeb(response.body), res);
+}
+export async function serveHttp(fn, port, log = console.log) {
+    const shutdown = new AbortController();
+    let inFlight = 0;
+    let idle;
+    const server = createServer(async (req, res) => {
+        inFlight++;
+        const client = new AbortController();
+        res.on("close", () => {
+            if (!res.writableFinished)
+                client.abort(new Error("client went away"));
+        });
+        const signal = AbortSignal.any([client.signal, shutdown.signal]);
+        try {
+            const response = await fn.handler(toRequest(req, signal), { signal });
+            if (!(response instanceof Response))
+                throw new TypeError("handler didn't return a Response");
+            await writeResponse(res, response, req.method === "HEAD");
+        }
+        catch (err) {
+            if (!client.signal.aborted) {
+                log(`${req.method} ${req.url}: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+            }
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("content-type", "text/plain; charset=utf-8");
+                res.end("Internal Server Error\n");
+            }
+            else {
+                res.destroy();
+            }
+        }
+        finally {
+            inFlight--;
+            if (inFlight === 0)
+                idle?.();
+        }
+    });
+    // Knative's queue-proxy keeps connections open; let it reuse them a while.
+    server.keepAliveTimeout = 65_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, () => resolve());
+    });
+    const addr = server.address();
+    const actual = typeof addr === "object" && addr ? addr.port : port;
+    return {
+        server,
+        port: actual,
+        async close(graceMs = 25_000) {
+            const closed = new Promise((r) => server.close(() => r()));
+            server.closeIdleConnections();
+            if (inFlight > 0) {
+                await Promise.race([
+                    new Promise((r) => (idle = r)),
+                    new Promise((r) => setTimeout(r, graceMs).unref()),
+                ]);
+            }
+            shutdown.abort(new Error("server shutting down"));
+            server.closeAllConnections();
+            await closed;
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+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";

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/queue.d.ts

@@ -0,0 +1,59 @@
+import pg from "pg";
+import { type Job, type QueueFunction } from "./define.ts";
+export declare const TABLE = "maxcloud_jobs";
+/**
+ * The query KEDA scales a queue's worker on: jobs due or being worked on.
+ * Counting running jobs too keeps a worker alive until its jobs finish.
+ */
+export declare function backlogQuery(queue: string): string;
+/** Anything that can run a query: a Pool, or a client inside a transaction. */
+export interface Queryable {
+    query: pg.Pool["query"];
+}
+/** The pool `enqueue` uses unless given a client. */
+export declare function defaultPool(): pg.Pool;
+/** Creates the table once per pool. Safe to race: the DDL runs under a lock. */
+export declare function ensureSchema(db: pg.Pool): Promise<void>;
+export interface EnqueueOptions {
+    /** Run no sooner than this many seconds from now. */
+    delaySeconds?: number;
+    /**
+     * Insert with this client, e.g. inside your own transaction, so the job
+     * exists only if the transaction commits. The table must already exist
+     * (any worker or earlier enqueue creates it).
+     */
+    client?: Queryable;
+}
+/**
+ * Adds a job to a queue and returns its id.
+ *
+ * ```ts
+ * await enqueue("images", { key: "uploads/cat.jpg" });
+ * ```
+ */
+export declare function enqueue<T>(queue: string | QueueFunction<T>, payload: T, options?: EnqueueOptions): Promise<string>;
+/** Claims the next due job, or one whose lease ran out. */
+export declare function claim(db: Queryable, queue: string, leaseSeconds: number): Promise<Job<unknown> | undefined>;
+export declare function complete(db: Queryable, id: string): Promise<void>;
+/** Schedules a retry with exponential backoff, or marks the job failed after its last attempt. */
+export declare function fail(db: Queryable, job: Job<unknown>, error: unknown, maxAttempts: number, backoffSeconds: number): Promise<"retry" | "failed">;
+/** Puts a job back without counting the attempt, for a worker shutting down. */
+export declare function release(db: Queryable, id: string): Promise<void>;
+/** Deletes finished jobs older than the given number of days. */
+export declare function prune(db: Queryable, days?: number): Promise<number>;
+export interface WorkerOptions {
+    /** Defaults to a pool on DATABASE_URL. */
+    pool?: pg.Pool;
+    /** Stops the worker: no new jobs; jobs in hand finish, or are put back at `graceMs`. */
+    signal: AbortSignal;
+    /** How long jobs in hand get to finish after `signal`. Default 25 s. */
+    graceMs?: number;
+    /** How often an idle worker looks for jobs (it's also woken on enqueue). Default 2 s. */
+    pollMs?: number;
+    log?: (msg: string) => void;
+}
+/**
+ * Works on a queue until `signal` aborts. Resolves once every job in hand is
+ * done or put back.
+ */
+export declare function runWorker(fn: QueueFunction<any>, opts: WorkerOptions): Promise<void>;

package/dist/queue.js

@@ -0,0 +1,214 @@
+// The job queue: one Postgres table, maxcloud_jobs, in the app's database
+// (DATABASE_URL). Workers claim rows with FOR UPDATE SKIP LOCKED, so two never
+// take the same job, and hold them on a lease: a worker that dies leaves its
+// job to be claimed again once the lease runs out.
+import pg from "pg";
+import { checkQueueName } from "./define.js";
+export const TABLE = "maxcloud_jobs";
+const CHANNEL = "maxcloud_jobs";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS ${TABLE} (
+  id bigserial PRIMARY KEY,
+  queue text NOT NULL,
+  payload jsonb NOT NULL DEFAULT '{}',
+  state text NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'running', 'done', 'failed')),
+  attempts integer NOT NULL DEFAULT 0,
+  run_after timestamptz NOT NULL DEFAULT now(),
+  locked_until timestamptz,
+  last_error text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  done_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS ${TABLE}_open ON ${TABLE} (queue, run_after, id) WHERE state IN ('pending', 'running');
+`;
+/**
+ * The query KEDA scales a queue's worker on: jobs due or being worked on.
+ * Counting running jobs too keeps a worker alive until its jobs finish.
+ */
+export function backlogQuery(queue) {
+    checkQueueName(queue);
+    return `SELECT count(*) FROM ${TABLE} WHERE queue = '${queue}' AND state IN ('pending', 'running') AND run_after <= now()`;
+}
+let pool;
+function databaseUrl() {
+    const url = process.env.DATABASE_URL;
+    if (!url)
+        throw new Error("DATABASE_URL isn't set: queues need the app's Postgres database");
+    return url;
+}
+/** The pool `enqueue` uses unless given a client. */
+export function defaultPool() {
+    pool ??= new pg.Pool({ connectionString: databaseUrl(), max: 4 });
+    return pool;
+}
+const ready = new WeakMap();
+/** Creates the table once per pool. Safe to race: the DDL runs under a lock. */
+export function ensureSchema(db) {
+    let p = ready.get(db);
+    if (!p) {
+        p = (async () => {
+            const client = await db.connect();
+            try {
+                await client.query("BEGIN");
+                await client.query(`SELECT pg_advisory_xact_lock(hashtext('${TABLE}'))`);
+                await client.query(SCHEMA);
+                await client.query("COMMIT");
+            }
+            catch (err) {
+                await client.query("ROLLBACK").catch(() => { });
+                throw err;
+            }
+            finally {
+                client.release();
+            }
+        })();
+        p.catch(() => ready.delete(db));
+        ready.set(db, p);
+    }
+    return p;
+}
+/**
+ * Adds a job to a queue and returns its id.
+ *
+ * ```ts
+ * await enqueue("images", { key: "uploads/cat.jpg" });
+ * ```
+ */
+export async function enqueue(queue, payload, options = {}) {
+    const name = typeof queue === "string" ? queue : queue.options.queue;
+    checkQueueName(name);
+    let db = options.client;
+    if (!db) {
+        const p = defaultPool();
+        await ensureSchema(p);
+        db = p;
+    }
+    const delay = Math.max(0, options.delaySeconds ?? 0);
+    const res = await db.query(`INSERT INTO ${TABLE} (queue, payload, run_after) VALUES ($1, $2, now() + make_interval(secs => $3)) RETURNING id`, [name, JSON.stringify(payload ?? null), delay]);
+    await db.query(`SELECT pg_notify('${CHANNEL}', $1)`, [name]);
+    return res.rows[0].id;
+}
+/** Claims the next due job, or one whose lease ran out. */
+export async function claim(db, queue, leaseSeconds) {
+    const res = await db.query(`UPDATE ${TABLE} j
+        SET state = 'running', attempts = j.attempts + 1, locked_until = now() + make_interval(secs => $2)
+       FROM (SELECT id FROM ${TABLE}
+              WHERE queue = $1 AND run_after <= now()
+                AND (state = 'pending' OR (state = 'running' AND locked_until < now()))
+              ORDER BY run_after, id
+              FOR UPDATE SKIP LOCKED
+              LIMIT 1) next
+      WHERE j.id = next.id
+      RETURNING j.id, j.queue, j.payload, j.attempts, j.created_at`, [queue, leaseSeconds]);
+    const r = res.rows[0];
+    if (!r)
+        return undefined;
+    return { id: r.id, queue: r.queue, payload: r.payload, attempt: r.attempts, createdAt: r.created_at };
+}
+export async function complete(db, id) {
+    await db.query(`UPDATE ${TABLE} SET state = 'done', done_at = now(), locked_until = NULL WHERE id = $1`, [id]);
+}
+/** Schedules a retry with exponential backoff, or marks the job failed after its last attempt. */
+export async function fail(db, job, error, maxAttempts, backoffSeconds) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    if (job.attempt >= maxAttempts) {
+        await db.query(`UPDATE ${TABLE} SET state = 'failed', done_at = now(), locked_until = NULL, last_error = $2 WHERE id = $1`, [job.id, message]);
+        return "failed";
+    }
+    const delay = backoffSeconds * 2 ** (job.attempt - 1);
+    await db.query(`UPDATE ${TABLE} SET state = 'pending', locked_until = NULL, last_error = $2, run_after = now() + make_interval(secs => $3) WHERE id = $1`, [job.id, message, delay]);
+    return "retry";
+}
+/** Puts a job back without counting the attempt, for a worker shutting down. */
+export async function release(db, id) {
+    await db.query(`UPDATE ${TABLE} SET state = 'pending', attempts = greatest(attempts - 1, 0), locked_until = NULL WHERE id = $1`, [id]);
+}
+/** Deletes finished jobs older than the given number of days. */
+export async function prune(db, days = 7) {
+    const res = await db.query(`DELETE FROM ${TABLE} WHERE state = 'done' AND done_at < now() - make_interval(days => $1)`, [days]);
+    return res.rowCount ?? 0;
+}
+/**
+ * Works on a queue until `signal` aborts. Resolves once every job in hand is
+ * done or put back.
+ */
+export async function runWorker(fn, opts) {
+    const o = fn.options;
+    const concurrency = Math.max(1, o.concurrency ?? 1);
+    const timeoutMs = (o.timeoutSeconds ?? 300) * 1000;
+    const lease = Math.ceil(timeoutMs / 1000) + 30;
+    const maxAttempts = o.maxAttempts ?? 5;
+    const backoff = o.backoffSeconds ?? 10;
+    const log = opts.log ?? ((m) => console.log(m));
+    const db = opts.pool ?? new pg.Pool({ connectionString: databaseUrl(), max: concurrency + 1 });
+    const ownPool = !opts.pool;
+    await ensureSchema(db);
+    await prune(db).catch(() => { });
+    // Wake idle slots when a job is enqueued, instead of waiting for the poll.
+    let wake = () => { };
+    let wakeup = new Promise((r) => (wake = r));
+    const poke = () => {
+        wake();
+        wakeup = new Promise((r) => (wake = r));
+    };
+    const listener = await db.connect();
+    listener.on("notification", (n) => {
+        if (n.payload === o.queue)
+            poke();
+    });
+    await listener.query(`LISTEN ${CHANNEL}`);
+    opts.signal.addEventListener("abort", poke, { once: true });
+    const stopping = opts.signal;
+    const shutdown = new AbortController();
+    stopping.addEventListener("abort", () => setTimeout(() => shutdown.abort(), opts.graceMs ?? 25_000).unref(), { once: true });
+    const work = async (job) => {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = AbortSignal.any([timeout, shutdown.signal]);
+        try {
+            await Promise.race([
+                fn.handler(job, { signal }),
+                new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true })),
+            ]);
+            await complete(db, job.id);
+            log(`job ${job.id} done (attempt ${job.attempt})`);
+        }
+        catch (err) {
+            if (shutdown.signal.aborted && !timeout.aborted) {
+                await release(db, job.id);
+                log(`job ${job.id} put back: worker shutting down`);
+                return;
+            }
+            const reason = timeout.aborted ? new Error(`timed out after ${timeoutMs / 1000}s`) : err;
+            const outcome = await fail(db, job, reason, maxAttempts, backoff);
+            log(`job ${job.id} ${outcome === "failed" ? "failed for good" : "failed, will retry"} (attempt ${job.attempt}/${maxAttempts}): ${reason instanceof Error ? reason.message : String(reason)}`);
+        }
+    };
+    const slot = async () => {
+        while (!stopping.aborted) {
+            let job;
+            try {
+                job = await claim(db, o.queue, lease);
+            }
+            catch (err) {
+                log(`claiming from ${o.queue}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (job) {
+                await work(job);
+                continue;
+            }
+            await Promise.race([wakeup, new Promise((r) => setTimeout(r, opts.pollMs ?? 2000).unref())]);
+        }
+    };
+    log(`worker for queue ${o.queue} started (concurrency ${concurrency})`);
+    try {
+        await Promise.all(Array.from({ length: concurrency }, slot));
+    }
+    finally {
+        await listener.query(`UNLISTEN ${CHANNEL}`).catch(() => { });
+        listener.release();
+        if (ownPool)
+            await db.end();
+    }
+    log(`worker for queue ${o.queue} stopped`);
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,62 @@
+import { type MaxcloudFunction } from "./define.ts";
+/** A Kubernetes-safe name for an export: resizeImage -> resize-image. */
+export declare function kubeName(exportName: string): string;
+export interface Found {
+    name: string;
+    exportName: string;
+    fn: MaxcloudFunction;
+}
+export declare function findFunctions(mod: Record<string, unknown>): Found[];
+/** Prefixes the describe line printed when MAXCLOUD_DESCRIBE=1 is set. */
+export declare const DESCRIBE_TAG = "maxcloud:describe:";
+/** What `--describe` prints, with every default filled in. */
+export declare function describe(found: Found[]): {
+    sdk: string;
+    version: string;
+    functions: ({
+        name: string;
+        export: string;
+        kind: "http" | "queue" | "schedule";
+        memory: string | null;
+        cpu: string | null;
+        public: boolean;
+        minInstances: number;
+        maxInstances: number;
+        concurrency: number;
+        timeoutSeconds: number;
+    } | {
+        name: string;
+        export: string;
+        kind: "http" | "queue" | "schedule";
+        memory: string | null;
+        cpu: string | null;
+        schedule: string;
+        timeZone: string;
+        retries: number;
+        timeoutSeconds: number;
+    } | {
+        name: string;
+        export: string;
+        kind: "http" | "queue" | "schedule";
+        memory: string | null;
+        cpu: string | null;
+        queue: string;
+        concurrency: number;
+        maxInstances: number;
+        maxAttempts: number;
+        backoffSeconds: number;
+        timeoutSeconds: number;
+        backlogQuery: string;
+    })[];
+};
+/** The app's entry module: --source, $FUNCTION_SOURCE, package.json's main, or index.js. */
+export declare function sourcePath(source?: string, cwd?: string): string;
+export declare function load(path: string): Promise<Found[]>;
+export interface RunOptions {
+    port?: number;
+    /** Ends the run: HTTP drains, a worker stops, a schedule is aborted. */
+    signal: AbortSignal;
+    log?: (msg: string) => void;
+}
+/** Runs one function until it's done (schedule) or `signal` aborts. Resolves to the exit code. */
+export declare function run(f: Found, opts: RunOptions): Promise<number>;

package/dist/runtime.js

@@ -0,0 +1,131 @@
+// The runtime: loads the app's module, finds its functions, and either
+// describes them (for mcloud, which turns them into manifests) or runs one.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isFunction } from "./define.js";
+import { serveHttp } from "./http.js";
+import { backlogQuery, runWorker } from "./queue.js";
+/** A Kubernetes-safe name for an export: resizeImage -> resize-image. */
+export function kubeName(exportName) {
+    const name = exportName
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/_/g, "-")
+        .toLowerCase();
+    if (!/^[a-z]([-a-z0-9]{0,38}[a-z0-9])?$/.test(name)) {
+        throw new Error(`export ${exportName}: its name (${name}) must start with a letter and be at most 40 letters, digits and dashes`);
+    }
+    return name;
+}
+export function findFunctions(mod) {
+    const out = [];
+    const names = new Set();
+    for (const [exportName, value] of Object.entries(mod)) {
+        if (!isFunction(value))
+            continue;
+        if (exportName === "default") {
+            throw new Error("a function is the default export; give it a named export instead, its name becomes the function's");
+        }
+        const name = kubeName(exportName);
+        if (names.has(name))
+            throw new Error(`two exports turn into the function name ${name}`);
+        names.add(name);
+        out.push({ name, exportName, fn: value });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Prefixes the describe line printed when MAXCLOUD_DESCRIBE=1 is set. */
+export const DESCRIBE_TAG = "maxcloud:describe:";
+/** What `--describe` prints, with every default filled in. */
+export function describe(found) {
+    return {
+        sdk: "@max-cloud/functions",
+        version: packageVersion(),
+        functions: found.map(({ name, exportName, fn }) => {
+            const base = { name, export: exportName, kind: fn.kind, memory: fn.options.memory ?? null, cpu: fn.options.cpu ?? null };
+            switch (fn.kind) {
+                case "http": {
+                    const o = fn.options;
+                    return { ...base, public: o.public ?? false, minInstances: o.minInstances ?? 0, maxInstances: o.maxInstances ?? 3, concurrency: o.concurrency ?? 0, timeoutSeconds: o.timeoutSeconds ?? 300 };
+                }
+                case "schedule": {
+                    const o = fn.options;
+                    return { ...base, schedule: o.schedule, timeZone: o.timeZone ?? "UTC", retries: o.retries ?? 0, timeoutSeconds: o.timeoutSeconds ?? 3600 };
+                }
+                case "queue": {
+                    const o = fn.options;
+                    return { ...base, queue: o.queue, concurrency: o.concurrency ?? 1, maxInstances: o.maxInstances ?? 3, maxAttempts: o.maxAttempts ?? 5, backoffSeconds: o.backoffSeconds ?? 10, timeoutSeconds: o.timeoutSeconds ?? 300, backlogQuery: backlogQuery(o.queue) };
+                }
+            }
+        }),
+    };
+}
+function packageVersion() {
+    try {
+        return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** The app's entry module: --source, $FUNCTION_SOURCE, package.json's main, or index.js. */
+export function sourcePath(source, cwd = process.cwd()) {
+    const s = source ?? process.env.FUNCTION_SOURCE;
+    if (s)
+        return resolve(cwd, s);
+    const pkgFile = resolve(cwd, "package.json");
+    if (existsSync(pkgFile)) {
+        const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+        if (typeof pkg.main === "string")
+            return resolve(cwd, pkg.main);
+    }
+    return resolve(cwd, "index.js");
+}
+export async function load(path) {
+    const mod = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+    return findFunctions(mod);
+}
+/** Runs one function until it's done (schedule) or `signal` aborts. Resolves to the exit code. */
+export async function run(f, opts) {
+    const log = opts.log ?? ((m) => console.log(m));
+    const fn = f.fn;
+    switch (fn.kind) {
+        case "http": {
+            const serving = await serveHttp(fn, opts.port ?? 8080, log);
+            log(`${f.name}: listening on port ${serving.port}`);
+            await new Promise((r) => opts.signal.addEventListener("abort", () => r(), { once: true }));
+            log(`${f.name}: shutting down`);
+            await serving.close();
+            return 0;
+        }
+        case "schedule": {
+            const timeout = (fn.options.timeoutSeconds ?? 3600) * 1000;
+            const signal = AbortSignal.any([opts.signal, AbortSignal.timeout(timeout)]);
+            const startedAt = new Date();
+            try {
+                await Promise.race([
+                    fn.handler({ signal, startedAt }),
+                    new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true })),
+                ]);
+                log(`${f.name}: done in ${((Date.now() - startedAt.getTime()) / 1000).toFixed(1)}s`);
+                return 0;
+            }
+            catch (err) {
+                log(`${f.name}: failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                return 1;
+            }
+        }
+        case "queue":
+            await runWorker(fn, { signal: opts.signal, log });
+            return 0;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@max-cloud/functions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write HTTP, scheduled and queue functions for maxcloud, the homelab's run platform",
+  "keywords": ["functions", "serverless", "knative", "keda"],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxemiliang/maxcloud.git",
+    "directory": "packages/functions"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "maxcloud-functions": "./dist/cli.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --test-concurrency=1 \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "pg": "^8.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "@types/pg": "^8.23.1",
+    "typescript": "^7.0.2"
+  }
+}