@velox0/cerver 0.4.2 → 0.5.0

package/README.md

@@ -1,9 +1,11 @@
-<div align="center">
-  <img src="templates/cerver.png" alt="Cerver Logo" width="120" />
-</div>
-
 # Cerver
 
+[![Publish](https://github.com/velox0/cerver/actions/workflows/publish.yml/badge.svg)](https://github.com/velox0/cerver/actions/workflows/publish.yml)
+[![CI](https://github.com/velox0/cerver/actions/workflows/ci.yml/badge.svg)](https://github.com/velox0/cerver/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@velox0/cerver)](https://www.npmjs.com/package/@velox0/cerver)
+
+<img src="templates/cerver.png" alt="Cerver Logo" width="200px" align="right" />
+
 A lightweight, compile-time web framework that transpiles restricted JavaScript server logic into highly optimized native C HTTP server binaries.
 
 Cerver takes a Next.js-style file-based routing structure (written in a strict subset of JavaScript), parses it, generates equivalent C code, embeds your static assets, and compiles it all into a single, standalone executable that runs with zero Node.js dependency.
@@ -11,10 +13,25 @@ Cerver takes a Next.js-style file-based routing structure (written in a strict s
 ## Features
 
 - **Compile-Time Framework**: Your JavaScript is parsed and compiled to native C. There is no JavaScript engine (like V8) or interpreter included in the final binary.
-- **Microscopic Footprint**: Generated executables are typically ~50KB and start in milliseconds.
+- **Microscopic Footprint**: Generated executables are tiny and start in milliseconds.
 - **Single-Binary Deployment**: Static assets (HTML, CSS, JS, images) are automatically minified and embedded directly into the executable as C byte arrays.
 - **Native Performance**: Uses `kqueue` (macOS) or `epoll` (Linux) event loops for high-performance non-blocking I/O.
-- **File-Based Routing**: Intuitive `app/routes/` directory structure, supporting dynamic segments (e.g., `/item/[id].js`).
+- **File-Based Routing**: Intuitive `routes/` directory structure, supporting dynamic segments (e.g., `/item/[id].js`).
+
+## Benchmarks (Autocannon)
+
+Local loopback runs against `localhost`, 20s per run.
+
+Note: timeouts only appear at the highest concurrency (240 connections). On a single machine, autocannon and the server compete for CPU and kernel resources; the timeouts are likely client/loopback saturation rather than server errors.
+
+| Connections | Pipelining | Avg req/s | Avg latency | p99 latency | Total read | Errors (timeouts) |
+| ----------- | ---------- | --------- | ----------- | ----------- | ---------- | ----------------- |
+| 60          | 1          | 123,005   | 0.01 ms     | 0 ms        | 21.0 GB    | 0                 |
+| 60          | 10         | 125,973   | 4.26 ms     | 10 ms       | 21.5 GB    | 0                 |
+| 120         | 1          | 124,214   | 0.15 ms     | 1 ms        | 21.2 GB    | 0                 |
+| 120         | 10         | 131,245   | 8.64 ms     | 15 ms       | 22.4 GB    | 0                 |
+| 240         | 1          | 124,890   | 0.54 ms     | 1 ms        | 21.3 GB    | 118 (timeout)     |
+| 240         | 10         | 123,677   | 9.87 ms     | 14 ms       | 21.1 GB    | 1540 (timeout)    |
 
 ## Getting Started
 
@@ -40,9 +57,9 @@ cerver run
 
 ## Routing
 
-Routes are defined in the `app/routes/` directory.
+Routes are defined in the `routes/` directory.
 
-`app/routes/index.js` (maps to `/`)
+`routes/index.js` (maps to `/`)
 
 ```javascript
 export function GET(req, res) {
@@ -50,7 +67,7 @@ export function GET(req, res) {
 }
 ```
 
-`app/routes/api/status.js` (maps to `/api/status`)
+`routes/api/status.js` (maps to `/api/status`)
 
 ```javascript
 export function GET(req, res) {
@@ -58,7 +75,7 @@ export function GET(req, res) {
 }
 ```
 
-`app/routes/users/[id].js` (maps to `/users/:id`)
+`routes/users/[id].js` (maps to `/users/:id`)
 
 ```javascript
 export function GET(req, res) {
@@ -67,6 +84,16 @@ export function GET(req, res) {
 }
 ```
 
+### Clean URL Asset Mapping
+
+Cerver has a special asset routing convention that prevents folder clutter:
+- **Root Index**: `public/index.html` is automatically served at the root `/`.
+- **Directory Indexing**: Nested `index.html` files inside directories (e.g. `public/page/index.html`) are **not** implicitly aliased to `/page` (they remain at `/page/index.html`).
+- **Clean Folder Slugs**: If an HTML file has the exact same name as its parent directory, it is mapped to the clean directory URL. For example:
+  - `public/about/about.html` maps to `/about` (and `/about/`)
+  - `public/blog/posts/posts.html` maps to `/blog/posts` (and `/blog/posts/`)
+- **Other Static Assets**: All other assets like CSS, JS, images, and non-directory-matching HTML files serve directly at their file paths (e.g., `public/about/style.css` maps to `/about/style.css`).
+
 ## The Request & Response Objects
 
 Because Cerver compiles to C, the API surface is restricted.

package/lib/assets/embed.js

@@ -82,6 +82,8 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   const algo = compression || "none";
 
   lines.push("/* Auto-generated embedded assets — do not edit */");
+  lines.push('#include "cerver.h"');
+  lines.push("#include <stddef.h>");
   lines.push("");
 
   const assetEntries = [];
@@ -155,14 +157,37 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
       brLen,
     });
 
-    /* Auto-alias: /any/path/index.html → /any/path */
-    if (asset.servePath.endsWith("/index.html")) {
-      const dirPath = asset.servePath === "/index.html"
-        ? "/"
-        : asset.servePath.slice(0, -"/index.html".length);
+    /* Auto-alias rule:
+       1. /index.html → /
+       2. /path/to/name/name.html → /path/to/name
+    */
+    let shouldAlias = false;
+    let aliasPath = null;
+
+    if (asset.servePath === "/index.html") {
+      shouldAlias = true;
+      aliasPath = "/";
+    } else if (asset.servePath.endsWith(".html")) {
+      const parts = asset.servePath.split("/");
+      if (parts.length >= 3) {
+        const fileNameWithExt = parts[parts.length - 1];
+        const parentDir = parts[parts.length - 2];
+        const baseName = fileNameWithExt.slice(0, -5); // Remove ".html"
+        if (baseName === parentDir) {
+          shouldAlias = true;
+          const lengthToRemove = fileNameWithExt.length + 1; // filename plus the slash before it
+          aliasPath = asset.servePath.slice(0, -lengthToRemove);
+          if (aliasPath === "") {
+            aliasPath = "/";
+          }
+        }
+      }
+    }
+
+    if (shouldAlias && aliasPath !== null) {
       assetEntries.push({
         name,
-        servePath: dirPath,
+        servePath: aliasPath,
         mime,
         gzName,
         gzLen,
@@ -173,7 +198,7 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   }
 
   /* Generate the asset table */
-  lines.push("static cerver_asset_t cerver_embedded_assets[] = {");
+  lines.push("cerver_asset_t cerver_embedded_assets[] = {");
   for (const entry of assetEntries) {
     lines.push(
       `    { "${entry.servePath}", "${entry.mime}", ` +
@@ -185,7 +210,7 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   }
   lines.push("};");
   lines.push(
-    `static const int cerver_embedded_asset_count = ${assetEntries.length};`
+    `const int cerver_embedded_asset_count = ${assetEntries.length};`
   );
 
   return lines.join("\n");

package/lib/codegen/dispatch_gen.js

@@ -40,7 +40,7 @@ function generateDispatch(routes) {
 
   /* Generate the dispatch function */
   lines.push(
-    "static cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req) {"
+    "cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req) {"
   );
   lines.push("    const char *path = req->path;");
   lines.push("    size_t path_len = 0;");
@@ -162,6 +162,9 @@ function generateDispatch(routes) {
             lines.push(
               `                req->params[req->params_count].value = seg${i}_start;`
             );
+            lines.push(
+              `                ((char*)seg${i}_start)[seg${i}_len] = '\\0';`
+            );
             lines.push(`                req->params_count++;`);
             paramIdx++;
           }

package/lib/codegen/generator.js

@@ -5,33 +5,36 @@ const { generateRouteTable } = require("./route_table");
 const { generateDispatch } = require("./dispatch_gen");
 
 /**
- * Generate the complete C server source file from IR routes.
+ * Generate server.c content.
  *
- * @param {IRRoute[]} routes - All IR routes
- * @param {object} config - Build config (port, embed, etc.)
- * @param {string|null} assetsCode - Generated embedded assets C code, or null
- * @returns {string} - Complete C source file
+ * @param {object} config - Build config (port, threads, etc.)
+ * @param {boolean} hasAssets - Whether embedding assets is enabled
+ * @returns {string} - C source for server.c
  */
-function generateServer(routes, config, assetsCode) {
+function generateServerC(config, hasAssets) {
   const lines = [];
 
-  /* ---- Header ---- */
   lines.push("/*");
   lines.push(" * Auto-generated by cerver — do not edit.");
   lines.push(" */");
   lines.push("");
   lines.push('#include "cerver.h"');
-  lines.push("");
   lines.push("#include <stdio.h>");
   lines.push("#include <stdlib.h>");
-  lines.push("#include <string.h>");
   lines.push("");
 
-  /* ---- Embedded assets (if any) ---- */
-  if (assetsCode) {
-    lines.push("/* ---- Embedded Assets ---- */");
-    lines.push("");
-    lines.push(assetsCode);
+  /* Routing externs */
+  lines.push("/* Routing and Handler declarations */");
+  lines.push("extern cerver_route_t cerver_routes[];");
+  lines.push("extern const int cerver_route_count;");
+  lines.push("extern cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req);");
+  lines.push("");
+
+  /* Asset declarations */
+  if (hasAssets) {
+    lines.push("/* Embedded Assets */");
+    lines.push("extern cerver_asset_t cerver_embedded_assets[];");
+    lines.push("extern const int cerver_embedded_asset_count;");
     lines.push("");
   } else {
     lines.push("/* No embedded assets */");
@@ -40,6 +43,63 @@ function generateServer(routes, config, assetsCode) {
     lines.push("");
   }
 
+  /* Main function */
+  lines.push("/* ---- Entry Point ---- */");
+  lines.push("");
+  lines.push("int main(int argc, char *argv[]) {");
+  lines.push("    (void)argc;");
+  lines.push("    (void)argv;");
+  lines.push("");
+  lines.push(`    int port = ${config.port};`);
+  lines.push("");
+  lines.push("    /* Allow PORT env override */");
+  lines.push('    const char *env_port = getenv("CERVER_PORT");');
+  lines.push('    if (!env_port) env_port = getenv("PORT");');
+  lines.push("    if (env_port) port = atoi(env_port);");
+  lines.push("");
+  lines.push("    cerver_server_t srv;");
+  lines.push(`    cerver_init(&srv, port, ${config.threads});`);
+  lines.push("");
+  lines.push(
+    "    cerver_add_routes(&srv, cerver_routes, cerver_route_count);"
+  );
+  lines.push("");
+  lines.push("    /* Use generated compile-time dispatch for fast routing */");
+  lines.push("    cerver_set_dispatch(&srv, cerver_generated_dispatch);");
+  lines.push("");
+  if (hasAssets) {
+    lines.push(
+      "    cerver_set_assets(&srv, cerver_embedded_assets, cerver_embedded_asset_count);"
+    );
+  } else {
+    lines.push('    cerver_set_public_dir(&srv, "./public");');
+  }
+  lines.push("");
+  lines.push("    return cerver_listen(&srv);");
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate routes.c content.
+ *
+ * @param {IRRoute[]} routes - All IR routes
+ * @returns {string} - C source for routes.c
+ */
+function generateRoutesC(routes) {
+  const lines = [];
+
+  lines.push("/*");
+  lines.push(" * Auto-generated route handler logic — do not edit.");
+  lines.push(" */");
+  lines.push("");
+  lines.push('#include "cerver.h"');
+  lines.push("#include <string.h>");
+  lines.push("#include <stdlib.h>");
+  lines.push("");
+
   /* ---- Route table (forward decls + table) ---- */
   lines.push("/* ---- Routes ---- */");
   lines.push("");
@@ -76,47 +136,22 @@ function generateServer(routes, config, assetsCode) {
   lines.push("");
   lines.push(generateDispatch(routes));
 
-  /* ---- Main function ---- */
-  lines.push("/* ---- Entry Point ---- */");
-  lines.push("");
-  lines.push("int main(int argc, char *argv[]) {");
-  lines.push("    (void)argc;");
-  lines.push("    (void)argv;");
-  lines.push("");
-  lines.push(`    int port = ${config.port};`);
-  lines.push("");
-  lines.push("    /* Allow PORT env override */");
-  lines.push('    const char *env_port = getenv("CERVER_PORT");');
-  lines.push('    if (!env_port) env_port = getenv("PORT");');
-  lines.push("    if (env_port) port = atoi(env_port);");
-  lines.push("");
-  lines.push("    cerver_server_t srv;");
-  lines.push(`    cerver_init(&srv, port, ${config.threads});`);
-  lines.push("");
-  lines.push(
-    "    cerver_add_routes(&srv, cerver_routes, cerver_route_count);"
-  );
-  lines.push("");
-
-  /* Wire up generated dispatch */
-  lines.push("    /* Use generated compile-time dispatch for fast routing */");
-  lines.push("    cerver_set_dispatch(&srv, cerver_generated_dispatch);");
-  lines.push("");
-
-  if (assetsCode) {
-    lines.push(
-      "    cerver_set_assets(&srv, cerver_embedded_assets, cerver_embedded_asset_count);"
-    );
-  } else {
-    lines.push('    cerver_set_public_dir(&srv, "./public");');
-  }
-
-  lines.push("");
-  lines.push("    return cerver_listen(&srv);");
-  lines.push("}");
-  lines.push("");
-
   return lines.join("\n");
 }
 
-module.exports = { generateServer };
+/**
+ * Generate the complete C server source structures from IR routes.
+ *
+ * @param {IRRoute[]} routes - All IR routes
+ * @param {object} config - Build config (port, embed, etc.)
+ * @param {boolean} hasAssets - Whether embedding assets is enabled
+ * @returns {{ serverC: string, routesC: string }} - Generated files object
+ */
+function generateServer(routes, config, hasAssets) {
+  return {
+    serverC: generateServerC(config, hasAssets),
+    routesC: generateRoutesC(routes),
+  };
+}
+
+module.exports = { generateServer, generateServerC, generateRoutesC };

package/lib/codegen/route_table.js

@@ -25,7 +25,7 @@ function generateRouteTable(routes) {
   lines.push("");
 
   /* Route table array */
-  lines.push("static cerver_route_t cerver_routes[] = {");
+  lines.push("cerver_route_t cerver_routes[] = {");
   for (const route of routes) {
     const name = handlerName(route.method, route.urlPath);
     lines.push(
@@ -34,7 +34,7 @@ function generateRouteTable(routes) {
   }
   lines.push("};");
   lines.push(
-    `static const int cerver_route_count = ${routes.length};`
+    `const int cerver_route_count = ${routes.length};`
   );
   lines.push("");
 

package/lib/commands/build.js

@@ -3,7 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 
-const { loadConfig } = require("../config");
+const { loadConfig, findProjectRoot } = require("../config");
 const { discoverRoutes } = require("../parser/discover");
 const { parseFile } = require("../parser/parse");
 const { validate } = require("../validator/validate");
@@ -17,7 +17,13 @@ const { compile: compileC } = require("../compiler/compile");
  * Full build pipeline: parse → validate → IR → codegen → compile
  */
 async function build(opts) {
-  const projectDir = process.cwd();
+  const projectDir = findProjectRoot();
+  if (!projectDir) {
+    console.log("Not a cerver project");
+    process.exit(1);
+  }
+  process.chdir(projectDir);
+
   const startTime = Date.now();
 
   console.log("\n  cerver build\n");
@@ -35,12 +41,15 @@ async function build(opts) {
   );
 
   /* ---- 2. Discover routes ---- */
-  const routesDir = path.join(projectDir, "app", "routes");
+  let routesDir = path.join(projectDir, "routes");
+  if (!fs.existsSync(routesDir)) {
+    routesDir = path.join(projectDir, "app", "routes");
+  }
   console.log("  → discovering routes...");
   const routeFiles = discoverRoutes(routesDir);
 
   if (routeFiles.length === 0) {
-    console.warn("  ⚠ no route files found in app/routes/");
+    console.warn(`  ⚠ no route files found in ${path.relative(projectDir, routesDir)}/`);
   } else {
     for (const r of routeFiles) {
       console.log(`    ${r.urlPath} ← ${path.relative(projectDir, r.filePath)}`);
@@ -81,7 +90,7 @@ async function build(opts) {
       assetsCode = await generateEmbeddedAssets(assets, config.minify, config.compression);
       console.log(
         `    ${assets.length} asset(s), ${(totalSize / 1024).toFixed(1)} KB total` +
-          (config.compression !== "none" ? ` (${config.compression} compressed)` : "")
+        (config.compression !== "none" ? ` (${config.compression} compressed)` : "")
       );
     } else {
       console.log("    no assets found in public/");
@@ -90,15 +99,29 @@ async function build(opts) {
 
   /* ---- 5. Generate C source ---- */
   console.log("  → generating C source...");
-  const cSource = generateServer(allRoutes, config, assetsCode);
+  const { serverC, routesC } = generateServer(allRoutes, config, !!assetsCode);
 
   /* Write to dist/ */
   const distDir = path.join(projectDir, "dist");
   fs.mkdirSync(distDir, { recursive: true });
 
   const serverCPath = path.join(distDir, "server.c");
-  fs.writeFileSync(serverCPath, cSource);
-  console.log(`    wrote ${(cSource.length / 1024).toFixed(1)} KB → dist/server.c`);
+  fs.writeFileSync(serverCPath, serverC);
+  console.log(`    wrote ${(serverC.length / 1024).toFixed(1)} KB → dist/server.c`);
+
+  const routesCPath = path.join(distDir, "routes.c");
+  fs.writeFileSync(routesCPath, routesC);
+  console.log(`    wrote ${(routesC.length / 1024).toFixed(1)} KB → dist/routes.c`);
+
+  const assetsCPath = path.join(distDir, "assets.c");
+  if (assetsCode) {
+    fs.writeFileSync(assetsCPath, assetsCode);
+    console.log(`    wrote ${(assetsCode.length / 1024).toFixed(1)} KB → dist/assets.c`);
+  } else {
+    if (fs.existsSync(assetsCPath)) {
+      fs.unlinkSync(assetsCPath);
+    }
+  }
 
   /* ---- 6. Copy runtime headers ---- */
   const runtimeDir = path.join(__dirname, "..", "..", "runtime");

package/lib/commands/dev.js

@@ -5,12 +5,19 @@ const path = require("path");
 const { spawn } = require("child_process");
 const chokidar = require("chokidar");
 const { build } = require("./build");
+const { findProjectRoot } = require("../config");
 
 /**
  * Dev mode: watch for changes, auto-rebuild, auto-restart.
  */
 async function dev(opts) {
-  const projectDir = process.cwd();
+  const projectDir = findProjectRoot();
+  if (!projectDir) {
+    console.log("Not a cerver project");
+    process.exit(1);
+  }
+  process.chdir(projectDir);
+
   const binaryPath = path.join(projectDir, "dist", "server");
 
   let serverProcess = null;
@@ -97,7 +104,7 @@ async function dev(opts) {
 
   /* ---- Watch for changes ---- */
   const watchPaths = [
-    path.join(projectDir, "app"),
+    path.join(projectDir, "routes"),
     path.join(projectDir, "public"),
     path.join(projectDir, "cerver.config.js"),
   ].filter((p) => fs.existsSync(p));