blumenjs 0.1.6 → 0.2.0

package/dist/templates/go-server/main.go

@@ -11,9 +11,14 @@ import (
 )
 
 const (
-	nodeSSRURL = "http://localhost:4000/render"
+	nodeSSRURL  = "http://localhost:4000/render"
+	nodeDataURL = "http://localhost:4000/data"
 )
 
+// Global page cache — stores rendered HTML in Go memory for near-instant responses.
+// Max 500 entries with LRU eviction. A single Go server can cache the entire site.
+var pageCache = NewPageCache(500)
+
 // SSRResponse from Node service
 type SSRResponse struct {
 	HTML  string                 `json:"html"`
@@ -28,6 +33,21 @@ type SSRRequest struct {
 	Data   map[string]interface{} `json:"data,omitempty"`
 }
 
+// DataRequest to Node /data endpoint
+type DataRequest struct {
+	Path    string                 `json:"path"`
+	Query   map[string][]string    `json:"query"`
+	Params  map[string]interface{} `json:"params"`
+	Headers map[string]string      `json:"headers,omitempty"`
+}
+
+// DataResponse from Node /data endpoint
+type DataResponse struct {
+	Props          map[string]interface{} `json:"props"`
+	HasServerProps bool                   `json:"hasServerProps"`
+	Revalidate     int                    `json:"revalidate"` // TTL in seconds
+}
+
 var httpClient = &http.Client{
 	Timeout: 10 * time.Second,
 }
@@ -35,8 +55,20 @@ var httpClient = &http.Client{
 func main() {
 	mux := http.NewServeMux()
 
-	// Static files are served directly — must be registered first
-	mux.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.Dir("static"))))
+	// Static files with immutable cache headers
+	staticHandler := http.StripPrefix("/static/", http.FileServer(http.Dir("static")))
+	mux.HandleFunc("/static/", func(w http.ResponseWriter, r *http.Request) {
+		// Set aggressive cache headers for static assets
+		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+		w.Header().Set("X-Blumen-Cache", "STATIC")
+		staticHandler.ServeHTTP(w, r)
+	})
+
+	// Image optimization endpoint - processes and caches images on the fly
+	mux.HandleFunc("/_blumen/image", ImageHandler())
+
+	// Cache management endpoint (for development/debugging)
+	mux.HandleFunc("/_blumen/cache", cacheStatusHandler)
 
 	// Specific routes with Go loaders for data fetching
 	mux.HandleFunc("/dashboard/settings", PageHandler(func(r *http.Request) (map[string]interface{}, error) {
@@ -46,16 +78,9 @@ func main() {
 		}, nil
 	}))
 
-	mux.HandleFunc("/users/{id}", PageHandler(func(r *http.Request) (map[string]interface{}, error) {
-		id := r.PathValue("id")
-		return map[string]interface{}{
-			"userId":      id,
-			"userProfile": "Profile data for user " + id + " fetched from Go db",
-		}, nil
-	}))
-
 	// Catch-all: forward every other request to the Node SSR server.
-	// This decouples Go from knowing about specific React page paths.
+	// If the page exports getServerProps, Node will fetch the data first.
+	// If a Go DataLoader is registered above, it takes priority.
 	mux.HandleFunc("/", PageHandler(nil))
 
 	startPort := 3000
@@ -73,6 +98,7 @@ func main() {
 	}
 
 	log.Printf("Go server starting on http://localhost:%d", startPort)
+	log.Printf("Page cache initialized (max %d entries)", 500)
 	if err := http.Serve(listener, mux); err != nil {
 		log.Fatalf("Server error: %v", err)
 	}
@@ -87,33 +113,114 @@ func PageHandler(loader DataLoader) http.HandlerFunc {
 			return
 		}
 
-		var props map[string]interface{}
-		var err error
-		if loader != nil {
-			props, err = loader(r)
-			if err != nil {
-				log.Printf("Loader error: %v", err)
-				http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+		// Generate cache key from the full URL (path + query string)
+		cacheKey := r.URL.RequestURI()
+
+		// Check the page cache first
+		if entry, found, stale := pageCache.Get(cacheKey); found {
+			// Handle ETag conditional request
+			if match := r.Header.Get("If-None-Match"); match == entry.ETag {
+				w.Header().Set("X-Blumen-Cache", "HIT")
+				w.WriteHeader(http.StatusNotModified)
 				return
 			}
-		}
 
-		// If this is a SPA data fetch request, return JSON props
-		if r.Header.Get("X-Blumen-Data") == "1" || r.URL.Query().Get("_data") == "1" {
-			w.Header().Set("Content-Type", "application/json")
-			if props == nil {
-				props = make(map[string]interface{})
+			if !stale {
+				// CACHE HIT: serve directly from Go memory (sub-millisecond)
+				serveCachedPage(w, entry, "HIT")
+				return
 			}
-			json.NewEncoder(w).Encode(props)
+
+			// STALE: serve stale content immediately, revalidate in background
+			serveCachedPage(w, entry, "STALE")
+
+			// Background revalidation (fire and forget)
+			go func() {
+				html, revalidate := renderPage(r, loader)
+				if html != "" {
+					pageCache.Set(cacheKey, html, revalidate)
+				}
+			}()
+			return
+		}
+
+		// CACHE MISS: render the page and cache the result
+		html, revalidate := renderPage(r, loader)
+		if html == "" {
+			// renderPage already wrote the error response
 			return
 		}
 
-		handleRouteWithProps(w, r, props)
+		// Cache the rendered page
+		pageCache.Set(cacheKey, html, revalidate)
+
+		// Serve the fresh response
+		entry, _, _ := pageCache.Get(cacheKey)
+		if entry != nil {
+			serveCachedPage(w, entry, "MISS")
+		} else {
+			// Fallback: serve directly without cache metadata
+			writeHTMLResponse(w, html, "MISS", "")
+		}
+	}
+}
+
+// serveCachedPage writes a cached page response with proper headers.
+func serveCachedPage(w http.ResponseWriter, entry *CacheEntry, cacheStatus string) {
+	writeHTMLResponse(w, entry.HTML, cacheStatus, entry.ETag)
+}
+
+// writeHTMLResponse writes an HTML response with cache and security headers.
+func writeHTMLResponse(w http.ResponseWriter, html string, cacheStatus string, etag string) {
+	// Security headers
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	w.Header().Set("X-Frame-Options", "DENY")
+	w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")
+
+	// Cache headers
+	w.Header().Set("X-Blumen-Cache", cacheStatus)
+	if etag != "" {
+		w.Header().Set("ETag", etag)
 	}
+	// Tell browsers and CDNs they can cache for 10s, serve stale for 60s while revalidating
+	w.Header().Set("Cache-Control", "public, s-maxage=10, stale-while-revalidate=60")
+
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte(html))
 }
 
-func handleRouteWithProps(w http.ResponseWriter, r *http.Request, props map[string]interface{}) {
-	// Prepare SSR request
+// renderPage performs the full SSR pipeline: fetch data + render HTML.
+// Returns the HTML string and the revalidation TTL in seconds.
+func renderPage(r *http.Request, loader DataLoader) (string, int) {
+	var props map[string]interface{}
+	var err error
+	revalidate := 0
+
+	if loader != nil {
+		// Use Go DataLoader (takes priority over getServerProps)
+		props, err = loader(r)
+		if err != nil {
+			log.Printf("Loader error: %v", err)
+			return "", 0
+		}
+	} else {
+		// No Go DataLoader - check if the page has getServerProps
+		tsProps, tsRevalidate, tsErr := fetchServerProps(r)
+		if tsErr != nil {
+			log.Printf("getServerProps error: %v", tsErr)
+			// Non-fatal: render the page without server props
+		} else if tsProps != nil {
+			props = tsProps
+			revalidate = tsRevalidate
+		}
+	}
+
+	// If this is a SPA data fetch request, return JSON props (don't cache)
+	// This check shouldn't happen in renderPage since it's called from the handler,
+	// but the handler already handles this case before reaching here.
+
+	// Call Node SSR to render the HTML
 	ssrReq := SSRRequest{
 		Path:  r.URL.Path,
 		Query: r.URL.Query(),
@@ -124,24 +231,64 @@ func handleRouteWithProps(w http.ResponseWriter, r *http.Request, props map[stri
 		Data: props,
 	}
 
-	// Call Node SSR service
 	ssrResp, err := callNodeSSR(ssrReq)
 	if err != nil {
 		log.Printf("SSR error: %v", err)
-		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
-		return
+		return "", 0
 	}
 
+	return ssrResp.HTML, revalidate
+}
 
+// fetchServerProps calls the Node SSR /data endpoint to run getServerProps.
+// Returns nil if the page doesn't export getServerProps.
+// Also returns the revalidate TTL (0 = no caching from getServerProps).
+func fetchServerProps(r *http.Request) (map[string]interface{}, int, error) {
+	// Build a subset of headers to forward
+	headers := make(map[string]string)
+	for _, key := range []string{"Authorization", "Cookie", "Accept-Language", "User-Agent"} {
+		if val := r.Header.Get(key); val != "" {
+			headers[key] = val
+		}
+	}
 
-	// Security headers
-	w.Header().Set("Content-Type", "text/html; charset=utf-8")
-	w.Header().Set("X-Content-Type-Options", "nosniff")
-	w.Header().Set("X-Frame-Options", "DENY")
-	w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")
+	dataReq := DataRequest{
+		Path:    r.URL.Path,
+		Query:   r.URL.Query(),
+		Params:  map[string]interface{}{},
+		Headers: headers,
+	}
 
-	w.WriteHeader(http.StatusOK)
-	w.Write([]byte(ssrResp.HTML))
+	reqBody, err := json.Marshal(dataReq)
+	if err != nil {
+		return nil, 0, fmt.Errorf("marshal data request: %w", err)
+	}
+
+	resp, err := httpClient.Post(
+		nodeDataURL,
+		"application/json",
+		bytes.NewReader(reqBody),
+	)
+	if err != nil {
+		return nil, 0, fmt.Errorf("http post /data: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, 0, fmt.Errorf("node /data returned %d", resp.StatusCode)
+	}
+
+	var dataResp DataResponse
+	if err := json.NewDecoder(resp.Body).Decode(&dataResp); err != nil {
+		return nil, 0, fmt.Errorf("decode data response: %w", err)
+	}
+
+	if !dataResp.HasServerProps {
+		// Page doesn't export getServerProps, skip
+		return nil, 0, nil
+	}
+
+	return dataResp.Props, dataResp.Revalidate, nil
 }
 
 func callNodeSSR(req SSRRequest) (*SSRResponse, error) {
@@ -172,4 +319,25 @@ func callNodeSSR(req SSRRequest) (*SSRResponse, error) {
 	return &ssrResp, nil
 }
 
-
+// cacheStatusHandler provides cache introspection for debugging.
+// GET /_blumen/cache — returns current cache size and status
+// DELETE /_blumen/cache — clears the entire cache
+func cacheStatusHandler(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"size":    pageCache.Size(),
+			"maxSize": 500,
+			"status":  "active",
+		})
+	case http.MethodDelete:
+		pageCache.Clear()
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"message": "Cache cleared",
+		})
+	default:
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+	}
+}

package/dist/templates/node-ssr/server.ts

@@ -3,7 +3,7 @@ import { renderToString } from "react-dom/server";
 import React from "react";
 
 // Auto-generated route map (run `npm run routes` to regenerate)
-import { routes, App, Document } from "./generated-routes";
+import { routes, App, Document, serverPropsMap } from "./generated-routes";
 import { matchRoute } from "../app/shared/router";
 import NotFoundPage from "../app/pages/NotFound";
 
@@ -21,6 +21,19 @@ interface SSRResponse {
 	props: Record<string, any>;
 }
 
+interface DataRequest {
+	path: string;
+	query: Record<string, string[]>;
+	params: Record<string, any>;
+	headers?: Record<string, string>;
+}
+
+interface DataResponse {
+	props: Record<string, any>;
+	hasServerProps: boolean;
+	revalidate: number; // TTL in seconds; 0 = no caching
+}
+
 const PORT = process.env.PORT || 4000;
 
 const server = http.createServer(async (req, res) => {
@@ -36,12 +49,97 @@ const server = http.createServer(async (req, res) => {
 		return;
 	}
 
-	if (req.method !== "POST" || req.url !== "/render") {
+	if (req.method !== "POST") {
 		res.writeHead(404);
 		res.end(JSON.stringify({ error: "Not Found" }));
 		return;
 	}
 
+	// Route to the correct handler
+	if (req.url === "/data") {
+		return handleData(req, res);
+	} else if (req.url === "/render") {
+		return handleRender(req, res);
+	} else {
+		res.writeHead(404);
+		res.end(JSON.stringify({ error: "Not Found" }));
+	}
+});
+
+/**
+ * POST /data - Execute getServerProps for a matched route.
+ *
+ * Called by the Go server before /render to fetch TypeScript-defined
+ * server data. If the page doesn't export getServerProps, returns
+ * { hasServerProps: false } and Go skips the data merge.
+ */
+async function handleData(req: http.IncomingMessage, res: http.ServerResponse) {
+	try {
+		const body = await readBody(req);
+		const dataReq: DataRequest = JSON.parse(body);
+
+		// Match the route to find the page
+		const match = matchRoute(dataReq.path, routes);
+
+		if (!match) {
+			res.writeHead(200);
+			res.end(JSON.stringify({ props: {}, hasServerProps: false }));
+			return;
+		}
+
+		// Find the route definition to look up in serverPropsMap
+		const routeDef = routes.find(r => r.component === match.component);
+		const getServerProps = routeDef ? serverPropsMap[routeDef.path] : undefined;
+
+		if (!getServerProps) {
+			// This page doesn't export getServerProps
+			res.writeHead(200);
+			res.end(JSON.stringify({ props: {}, hasServerProps: false }));
+			return;
+		}
+
+		// Build the BlumenContext
+		const ctx = {
+			params: { ...(dataReq.params || {}), ...match.params },
+			query: dataReq.query || {},
+			path: dataReq.path,
+			headers: dataReq.headers || {},
+		};
+
+		// Run getServerProps
+		const result = await getServerProps(ctx);
+
+		const dataResp: DataResponse = {
+			props: result?.props || {},
+			hasServerProps: true,
+			revalidate: result?.revalidate || 0,
+		};
+
+		res.writeHead(200);
+		res.end(JSON.stringify(dataResp));
+	} catch (error) {
+		console.error("getServerProps Error:", error);
+		res.writeHead(500);
+		res.end(
+			JSON.stringify({
+				error: "getServerProps failed",
+				message:
+					process.env.NODE_ENV === "development" ? String(error) : undefined,
+			}),
+		);
+	}
+}
+
+/**
+ * POST /render - Render the matched page to HTML.
+ *
+ * This is the existing SSR endpoint. It receives props (possibly
+ * enriched by /data) and renders the React component tree to HTML.
+ */
+async function handleRender(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+) {
 	try {
 		// Parse request body
 		const body = await readBody(req);
@@ -57,7 +155,11 @@ const server = http.createServer(async (req, res) => {
 				status: 404,
 				serverRendered: true,
 			};
-			const element = React.createElement(NotFound, props);
+			const element = React.createElement(
+				"div",
+				{ className: "page-transition page-transition-active" },
+				React.createElement(NotFound, props),
+			);
 			const html = renderToString(element);
 
 			res.writeHead(200);
@@ -76,10 +178,16 @@ const server = http.createServer(async (req, res) => {
 		};
 
 		// Render React to HTML
-		const appElement = React.createElement(App, {
-			Component: match.component,
-			pageProps: props,
-		});
+		// Wrap in the same page-transition div that the client-side
+		// RouterProvider renders, so hydration trees match exactly.
+		const appElement = React.createElement(
+			"div",
+			{ className: "page-transition page-transition-active" },
+			React.createElement(App, {
+				Component: match.component,
+				pageProps: props,
+			}),
+		);
 
 		const documentElement = React.createElement(Document, {
 			initialProps: props,
@@ -106,7 +214,7 @@ const server = http.createServer(async (req, res) => {
 			}),
 		);
 	}
-});
+}
 
 function readBody(req: http.IncomingMessage): Promise<string> {
 	return new Promise((resolve, reject) => {
@@ -123,6 +231,10 @@ function readBody(req: http.IncomingMessage): Promise<string> {
 
 server.listen(PORT, () => {
 	console.log(`Node SSR server running on http://localhost:${PORT}`);
+	const gspCount = Object.keys(serverPropsMap).length;
+	if (gspCount > 0) {
+		console.log(`  ${gspCount} page(s) with getServerProps detected`);
+	}
 });
 
 // Handle graceful shutdown

package/dist/templates/scripts/generate-routes.ts

@@ -40,6 +40,8 @@ interface RouteEntry {
 	patternStr: string;
 	/** Extracted parameter keys */
 	keys: string[];
+	/** Whether this page exports a getServerProps function */
+	hasGetServerProps: boolean;
 }
 
 function scanDir(dir: string, baseDir: string = dir): RouteEntry[] {
@@ -87,12 +89,17 @@ function scanDir(dir: string, baseDir: string = dir): RouteEntry[] {
 				patternStr = `^${patternStr}$`;
 			}
 
+			// Check if the page exports getServerProps
+			const fileContent = fs.readFileSync(fullPath, "utf-8");
+			const hasGetServerProps = /export\s+(async\s+)?function\s+getServerProps/.test(fileContent);
+
 			results.push({
 				route: routePath,
 				componentId,
 				importPath: relPath.replace(".tsx", "").replace(/\\/g, "/"),
 				patternStr,
-				keys
+				keys,
+				hasGetServerProps
 			});
 		}
 	}
@@ -139,6 +146,18 @@ function generateRouteFile(
 			`import ${r.componentId} from "${importPathPrefix}/${r.importPath}";`,
 	);
 
+	// For SSR: import getServerProps from pages that export it
+	const gspImports: string[] = [];
+	const gspRoutes = routes.filter(r => r.hasGetServerProps);
+	if (isServer && gspRoutes.length > 0) {
+		for (const r of gspRoutes) {
+			const gspId = "gsp_" + r.componentId.replace("Page_", "");
+			gspImports.push(
+				`import { getServerProps as ${gspId} } from "${importPathPrefix}/${r.importPath}";`,
+			);
+		}
+	}
+
 	const hasApp = fs.existsSync(path.join(PAGES_DIR, "_app.tsx"));
 	const hasDoc = fs.existsSync(path.join(PAGES_DIR, "_document.tsx"));
 
@@ -163,6 +182,25 @@ function generateRouteFile(
 \t}`;
 	});
 
+	// Generate serverPropsMap for SSR routes
+	let serverPropsMapStr = "";
+	if (isServer && gspRoutes.length > 0) {
+		const entries = gspRoutes.map(r => {
+			const gspId = "gsp_" + r.componentId.replace("Page_", "");
+			return `\t"${r.route}": ${gspId},`;
+		});
+		serverPropsMapStr = [
+			"",
+			"// Map of routes that export getServerProps",
+			"// Used by the SSR server to run data fetching before rendering",
+			"export const serverPropsMap: Record<string, Function> = {",
+			...entries,
+			"};",
+		].join("\n");
+	} else if (isServer) {
+		serverPropsMapStr = "\nexport const serverPropsMap: Record<string, Function> = {};";
+	}
+
 	const map = [
 		"",
 		"export interface RouteDef {",
@@ -178,10 +216,11 @@ function generateRouteFile(
 		"",
 		appImport,
 		docImport,
+		serverPropsMapStr,
 		"",
 	];
 
-	return [...header, ...imports, ...map].join("\n");
+	return [...header, ...imports, ...gspImports, ...map].join("\n");
 }
 
 function main() {
@@ -197,7 +236,8 @@ function main() {
 
 	console.log(`   Found ${routes.length} route(s):`);
 	for (const r of routes) {
-		console.log(`     ${r.route.padEnd(25)} → ${r.importPath}.tsx`);
+		const gspTag = r.hasGetServerProps ? " [getServerProps]" : "";
+		console.log(`     ${r.route.padEnd(25)} → ${r.importPath}.tsx${gspTag}`);
 	}
 
 	// Generate SSR routes (node-ssr/ → ../app/pages)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blumenjs",
-	"version": "0.1.6",
+	"version": "0.2.0",
 	"description": "The React framework powered by Go. Lightning-fast SSR with the DX you deserve.",
 	"type": "module",
 	"bin": {
@@ -26,9 +26,9 @@
 		"dev:legacy": "npm run routes && concurrently \"npm run dev:client\" \"npm run dev:ssr\" \"npm run dev:go\"",
 		"dev:client": "webpack serve --mode development",
 		"dev:ssr": "NODE_ENV=development tsx watch node-ssr/server.ts",
-		"dev:go": "go run go-server/main.go",
+		"dev:go": "go run go-server/main.go go-server/image.go go-server/cache.go",
 		"build:client": "webpack --mode production",
-		"build:ssr": "esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --external:react --external:react-dom",
+		"build:ssr": "esbuild node-ssr/server.ts --bundle --platform=node --format=esm --outfile=dist/ssr-server.js --packages=external",
 		"clean": "rm -rf dist static/js/bundle.js"
 	},
 	"keywords": [
@@ -64,12 +64,16 @@
 		"@types/react-dom": "^18.2.0",
 		"babel-loader": "^10.1.1",
 		"concurrently": "^8.2.2",
+		"css-loader": "^7.1.4",
 		"esbuild": "^0.19.0",
+		"mini-css-extract-plugin": "^2.10.2",
 		"react-refresh": "^0.18.0",
+		"style-loader": "^4.0.0",
 		"ts-loader": "^9.5.1",
 		"tsx": "^4.6.0",
 		"typescript": "^5.3.0",
 		"webpack": "^5.89.0",
+		"webpack-bundle-analyzer": "^5.3.0",
 		"webpack-cli": "^5.1.4",
 		"webpack-dev-server": "^5.2.3"
 	},