create-nodejs-fn 0.0.2 → 0.1.0

package/README.md

@@ -162,27 +162,33 @@ Visit `http://localhost:5173/clock` to see a dynamically generated image with th
 
 ## 🪄 The Black Magic Revealed
 
-### 1️⃣ Transparent Proxy Generation via AST Transformation
+### 1️⃣ Extract `nodejsFn` Contents (Clip & Crop)
 
-Uses `ts-morph` to **statically analyze** `*.container.ts` files.
-Detects exported functions and **auto-generates proxy functions with identical type signatures**.
+The plugin uses `ts-morph` to **statically analyze** `*.container.ts` files and **extracts the function bodies** wrapped in `nodejsFn()`.
 
 ```typescript
 // Your code (clock.container.ts)
 export const renderClock = nodejsFn(async () => {
-  // Node.js native processing...
+  const canvas = createCanvas(600, 200);
+  // ... Node.js native processing
   return pngDataUrl;
 });
 
-// 🧙 The plugin auto-generates a proxy
-// → Types fully preserved! IDE autocomplete works!
-// → Calls are routed to the container via RPC!
+// 🧙 Plugin extracts the inner function from nodejsFn()
+// → Only the function body is clipped out for the container!
 ```
 
-### 2️⃣ Container Management via Durable Objects
+### 2️⃣ Bundle & Build Docker Image
+
+The extracted functions are **bundled with esbuild** and combined with an auto-generated **Dockerfile** to create a Docker image.
+
+- Functions are bundled as a Cap'n Proto RPC server
+- Native dependencies specified in `external` are auto-extracted to `package.json`
+- Dockerfile is auto-generated and image is built
 
-Uses Cloudflare **Durable Objects** to manage container connections.
-Stateful, with multi-instance routing support!
+### 3️⃣ Deploy as Cloudflare Containers
+
+The generated Docker image is **bundled as Cloudflare Containers**, with **Durable Objects** managing the container lifecycle.
 
 ```typescript
 // Route to specific instances with containerKey
@@ -195,11 +201,21 @@ export const renderClock = nodejsFn(
 );
 ```
 
-### 3️⃣ Fully Automated Build with esbuild + Docker
+### 4️⃣ Auto-Replace Imports with Container Calls
 
-- Bundles container server code with **esbuild**
-- **Auto-generates Dockerfile**
-- Native deps specified in `external` are auto-extracted to `package.json`
+Imports to `*.container.ts` files are **automatically replaced with proxy module imports** by the Vite plugin.
+
+```typescript
+// Your code
+import { renderClock } from "./clock.container";
+
+// 🧙 Plugin auto-transforms this!
+// → Actually imports a generated proxy function
+// → Calls are transparently converted to Container RPC!
+// → Types are fully preserved! IDE autocomplete works!
+```
+
+**Result**: Code that looks like normal function calls actually executes inside Docker containers!
 
 
 ## ⚙️ Plugin Options
@@ -236,6 +252,10 @@ createNodejsFnPlugin({
     preInstallCommands: [],
     postInstallCommands: [],
     env: { MY_VAR: "value" },
+    // Run as a non-root user inside the container
+    user: { name: "app", uid: 1000, gid: 1000 },
+    // Or replace everything above with a fully custom Dockerfile
+    // dockerfilePath: "./containers/native.Dockerfile",
   },
   
   // Environment variables to pass from Worker to Container
@@ -249,6 +269,9 @@ createNodejsFnPlugin({
 });
 ```
 
+- `docker.user` lets you switch the runtime to a non-root user after installs while keeping generated paths (`/app`) writable.
+- To own the entire build, supply `docker: { dockerfilePath: "./containers/native.Dockerfile" }`. The type prevents mixing this with other docker options so you don't accidentally combine incompatible settings. If the custom Dockerfile doesn't already start `server.mjs`, the generator will append `CMD ["node", "./server.mjs"]` to the end.
+
 ---
 
 ## 🏗️ Internal Architecture
@@ -259,11 +282,13 @@ project/
 │   ├── clock.container.ts        # Your code
 │   ├── index.ts                  # Worker entry
 │   └── __generated__/            # 🧙 Auto-generated magic
-│       ├── create-nodejs-fn.ts         # RPC client & type definitions
-│       ├── create-nodejs-fn.do.ts      # Durable Object class
-│       ├── create-nodejs-fn.context.ts # Container key resolution
-│       ├── create-nodejs-fn.runtime.ts # nodejsFn / containerKey helpers
-│       └── proxy.src__clock.container.ts # Proxy functions
+│       ├── create-nodejs-fn.ts            # RPC client & type definitions
+│       ├── create-nodejs-fn.do.ts         # Durable Object class
+│       ├── create-nodejs-fn.context.ts    # Container key resolution
+│       ├── create-nodejs-fn.runtime.ts    # nodejsFn / containerKey helpers
+│       ├── create-nodejs-fn-stub-batch.ts # Cap'n Proto RPC batch client
+│       └── __proxies__/
+│           └── p-XXXXXXXX.ts              # Proxy functions (hashed)
 │
 └── .create-nodejs-fn/            # 🐳 Container build artifacts
     ├── Dockerfile                # Auto-generated

package/dist/index.d.mts

@@ -1,13 +1,28 @@
 import { Plugin } from 'vite';
 
-type DockerOptions = {
+type DockerUser = {
+    name: string;
+    uid?: number;
+    gid?: number;
+};
+type GeneratedDockerOptions = {
     baseImage?: string;
     systemPackages?: string[];
     preInstallCommands?: string[];
     postInstallCommands?: string[];
     env?: Record<string, string>;
     extraLines?: string[];
+    /**
+     * Create and switch to a non-root runtime user.
+     * Package installs still run as root; the user is applied before CMD.
+     */
+    user?: DockerUser;
+};
+type CustomDockerfileOption = {
+    /** Use a fully custom Dockerfile (path resolved from project root). */
+    dockerfilePath: string;
 };
+type DockerOptions = GeneratedDockerOptions | CustomDockerfileOption;
 type Opts = {
     files?: string[];
     generatedDir?: string;

package/dist/index.mjs

@@ -63,6 +63,9 @@ function collectExternalDeps(rootPkgPath, needed) {
     dependencies: out
   };
 }
+function isCustomDockerfile(opts) {
+  return Boolean(opts && "dockerfilePath" in opts && typeof opts.dockerfilePath === "string");
+}
 async function buildContainerServer(opts) {
   const { mods, outBaseAbs, dockerOpts, containerPort, external, root } = opts;
   ensureDir(outBaseAbs);
@@ -139,12 +142,35 @@ http.createServer((req, res) => {
 `
     );
   }
+  if (isCustomDockerfile(dockerOpts)) {
+    const customPath = path.resolve(root, dockerOpts.dockerfilePath);
+    if (!fs.existsSync(customPath)) {
+      throw new Error(
+        `[create-nodejs-fn] Custom Dockerfile not found: ${dockerOpts.dockerfilePath} (resolved to ${customPath})`
+      );
+    }
+    let customDockerfile = fs.readFileSync(customPath, "utf8");
+    if (!/server\.mjs/.test(customDockerfile) || !/\b(CMD|ENTRYPOINT)\b/.test(customDockerfile)) {
+      const trimmed = customDockerfile.replace(/\s*$/, "");
+      const suffix = [
+        trimmed,
+        "",
+        "# create-nodejs-fn runtime start",
+        'CMD ["node", "./server.mjs"]',
+        ""
+      ].join("\n");
+      customDockerfile = suffix;
+    }
+    writeFileIfChanged(dockerfile, customDockerfile);
+    return;
+  }
   const {
     baseImage = "node:20-slim",
     systemPackages = [],
     preInstallCommands = [],
     postInstallCommands = [],
-    env: dockerEnv = {}
+    env: dockerEnv = {},
+    user
   } = dockerOpts ?? {};
   const installLines = "RUN corepack enable && pnpm install --prod --no-frozen-lockfile";
   const sysDeps = systemPackages.length > 0 ? [
@@ -158,6 +184,13 @@ http.createServer((req, res) => {
     "ENV NODE_ENV=production",
     ...Object.entries(dockerEnv).map(([k, v]) => `ENV ${k}=${JSON.stringify(v ?? "")}`)
   ];
+  const userLines = user && user.name ? [
+    "# Runtime user (from plugin options)",
+    `RUN groupadd --system${user.gid ? ` --gid ${user.gid}` : ""} ${user.name} \\`,
+    `    && useradd --system --create-home --no-log-init --home-dir /home/${user.name} --gid ${user.name}${user.uid ? ` --uid ${user.uid}` : ""} ${user.name}`,
+    `RUN mkdir -p /app && chown -R ${user.name}:${user.name} /app`,
+    `USER ${user.name}`
+  ] : [];
   writeFileIfChanged(
     dockerfile,
     [
@@ -173,6 +206,7 @@ http.createServer((req, res) => {
       "COPY ./server.mjs ./server.mjs",
       ...envLines,
       ...postRuns,
+      ...userLines,
       `EXPOSE ${containerPort}`,
       `CMD ["node", "./server.mjs"]`,
       ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nodejs-fn",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Vite plugin to enable calling Node.js-dependent functions directly from Cloudflare Workers!!",
   "main": "dist/index.js",
   "module": "dist/index.mjs",