feat: LOW_RESOURCE mode + fedhost-proxy Rust crate skeleton

LOW_RESOURCE=true (volunteer node / Raspberry Pi profile)
- resourceConfig.ts: single source of truth for all constrained values
  DB pool: 20→5 connections, min 2→1
  Domain LRU cache: 10K→500 entries
  File LRU cache: 50K→2000 entries
  Analytics flush: 1min→5min
  Health check: 2min→10min
  Log level: info→warn
  Global rate limit: 300→60 req/min
  Upload rate limit: 60→10/min
  Compression: level 6→1 (fastest)
  Gossip interval: 5min→10min
- index.ts: imports resourceConfig FIRST, applies env overrides before any
  module initialises (pool, logger, caches, rate limiters all pick up values)
- app.ts: compression({ level: COMPRESSION_LEVEL })
- rateLimiter.ts: GLOBAL_RATE_LIMIT + UPLOAD_RATE_LIMIT from resourceConfig
- .env.example: full LOW_RESOURCE documentation with before/after table
- docker-compose.yml: LOW_RESOURCE: 'true' as commented option
- docs/SELF_HOSTING.md: full section — what changes, what doesn't,
  expected capacity on Pi 4 (4GB), tips for constrained nodes

crates/fedhost-proxy — Rust extraction skeleton
- Cargo.toml: axum 0.7, tokio, aws-sdk-s3, deadpool-postgres, redis,
  ed25519-dalek, prom-client; release profile strips + LTO + panic=abort
- main.rs: entry point, module layout, full architecture doc comment
- config.rs: all env vars via clap derive + dotenvy, LOW_RESOURCE overrides
- cache.rs: DomainCache + FileCache with TTL, in-process LRU, invalidation
- db.rs: read-only pool — lookup_site (primary + custom domain), lookup_file,
  record_hit; SQL matches TypeScript schema exactly
- handler.rs: full request flow skeleton — domain resolve, ACL check,
  file path resolve, S3 stream, analytics fire-and-forget, geo routing stub;
  HMAC cookie verification is a complete port of TypeScript verifyUnlockCookie
- storage.rs: ObjectStorage skeleton with todo!() for SDK wiring
- geo.rs: infer_region (Fly/Cloudflare/CloudFront headers), fly_to_aws,
  country_to_region (Indonesia → ap-southeast-3 priority)
- metrics.rs: stub Prometheus endpoint on separate port
- README.md: architecture diagram, module map, 9-item implementation roadmap,
  Caddy routing config, protocol compatibility requirements

Author: The No Hands Company

.env.example

@@ -220,3 +220,19 @@ DYNAMIC_PORT_END=9999
 
 # Maximum restarts before a crashed process is abandoned (default: 5)
 DYNAMIC_MAX_RESTARTS=5
+
+# ── Low-Resource Mode (Raspberry Pi / volunteer nodes) ────────────────────────
+# Set to "true" on constrained hardware to reduce memory and CPU usage.
+# All features remain available — throughput is reduced but federation works.
+# Typical hardware: Raspberry Pi 3/4, old laptops, 512MB-1GB RAM VMs.
+#
+# What changes with LOW_RESOURCE=true:
+#   DB pool connections: 20 → 5
+#   Domain LRU cache:    10 000 → 500 entries
+#   File LRU cache:      50 000 → 2 000 entries
+#   Analytics flush:     1 min  → 5 min
+#   Health check:        2 min  → 10 min
+#   Log level:           info   → warn
+#   Global rate limit:   300    → 60 req/min
+#   Compression:         level 6 → level 1 (fastest)
+LOW_RESOURCE=false

artifacts/api-server/src/app.ts

@@ -2,6 +2,7 @@ import express, { type Express, type Request, type Response, type NextFunction }
 import cors from "cors";
 import helmet from "helmet";
 import compression from "compression";
+import { COMPRESSION_LEVEL } from "./lib/resourceConfig";
 import cookieParser from "cookie-parser";
 import pinoHttp from "pino-http";
 import { randomUUID } from "crypto";
@@ -56,7 +57,7 @@ app.use(
 app.use(cors({ credentials: true, origin: allowedOrigins }));
 
 // ── Response compression ──────────────────────────────────────────────────────
-app.use(compression());
+app.use(compression({ level: COMPRESSION_LEVEL }));
 
 // ── Request IDs ───────────────────────────────────────────────────────────────
 app.use((req: Request, res: Response, next: NextFunction) => {

artifacts/api-server/src/index.ts

@@ -2,7 +2,26 @@ import app from "./app";
 import { db, nodesTable } from "@workspace/db";
 import { eq } from "drizzle-orm";
 import { generateKeyPair } from "./lib/federation";
-import { startHealthMonitor } from "./lib/healthMonitor";
+// ── Resource configuration — MUST be imported before anything that reads env vars ──
+import {
+  LOW_RESOURCE, DB_POOL, LOG_LEVEL,
+  ANALYTICS_FLUSH_INTERVAL_MS, HEALTH_CHECK_INTERVAL_MS, GOSSIP_INTERVAL_MS,
+} from "./lib/resourceConfig";
+
+// Apply LOW_RESOURCE overrides to process.env NOW so all downstream modules
+// (db pool, logger, caches, rate limiters) pick up constrained values at init time.
+if (LOW_RESOURCE) {
+  process.env.DB_POOL_MAX                 = String(DB_POOL.max);
+  process.env.DB_POOL_MIN                 = String(DB_POOL.min);
+  process.env.DB_IDLE_TIMEOUT_MS          = String(DB_POOL.idleTimeoutMillis);
+  process.env.DB_CONNECT_TIMEOUT_MS       = String(DB_POOL.connectionTimeoutMillis);
+  process.env.LOG_LEVEL                   = LOG_LEVEL;
+  process.env.ANALYTICS_FLUSH_INTERVAL_MS = String(ANALYTICS_FLUSH_INTERVAL_MS);
+  process.env.HEALTH_CHECK_INTERVAL_MS    = String(HEALTH_CHECK_INTERVAL_MS);
+  process.env.GOSSIP_INTERVAL_MS          = String(GOSSIP_INTERVAL_MS);
+  process.env.DOMAIN_CACHE_MAX            = process.env.DOMAIN_CACHE_MAX ?? "500";
+  process.env.FILE_CACHE_MAX              = process.env.FILE_CACHE_MAX   ?? "2000";
+}
 import { startAnalyticsFlusher, stopAnalyticsFlusher } from "./lib/analyticsFlush";
 import { startGossipPusher, stopGossipPusher } from "./routes/gossip";
 import { getRedisClient, closeRedis } from "./lib/redis";

artifacts/api-server/src/lib/resourceConfig.ts

@@ -0,0 +1,97 @@
+/**
+ * Low-resource mode configuration.
+ *
+ * Set LOW_RESOURCE=true to run FedHost on constrained hardware:
+ * Raspberry Pi, old laptops, small VMs (1 vCPU / 512 MB RAM).
+ *
+ * This is the Indonesian volunteer-node profile. A node running in
+ * low-resource mode still federates correctly — it just serves fewer
+ * concurrent requests and uses less memory.
+ *
+ * What changes:
+ *   DB pool:          max 5 connections  (default: 20)
+ *   DB pool min:      1                  (default: 2)
+ *   Log level:        warn               (default: info — cuts ~30% log I/O)
+ *   Domain cache:     500 entries        (default: 10 000)
+ *   File cache:       2 000 entries      (default: 50 000)
+ *   Analytics flush:  5 minutes          (default: 1 minute)
+ *   Health check:     10 minutes         (default: 2 minutes)
+ *   Site health:      30 minutes         (default: 10 minutes)
+ *   Global rate limit: 60/min            (default: 300/min)
+ *   Concurrent uploads: 2               (default: 60/min)
+ *   Compression level: 1 (fastest)       (default: zlib default ~6)
+ *   Pino pretty-print: disabled          (always disabled in prod anyway)
+ *
+ * What does NOT change:
+ *   Federation protocol — identical wire format, signatures, gossip
+ *   ACME / TLS — still works
+ *   Redis integration — still works if REDIS_URL is set
+ *   All API routes — fully available
+ *   Auth — unchanged
+ */
+
+export const LOW_RESOURCE = process.env.LOW_RESOURCE === "true";
+
+/** Database connection pool limits */
+export const DB_POOL = LOW_RESOURCE
+  ? { max: 5, min: 1, idleTimeoutMillis: 60_000, connectionTimeoutMillis: 8_000 }
+  : {
+      max:  parseInt(process.env.DB_POOL_MAX  ?? "20"),
+      min:  parseInt(process.env.DB_POOL_MIN  ?? "2"),
+      idleTimeoutMillis:       parseInt(process.env.DB_IDLE_TIMEOUT_MS    ?? "30000"),
+      connectionTimeoutMillis: parseInt(process.env.DB_CONNECT_TIMEOUT_MS ?? "5000"),
+    };
+
+/** Pino log level */
+export const LOG_LEVEL: string = LOW_RESOURCE
+  ? (process.env.LOG_LEVEL ?? "warn")           // quieter on low-RAM nodes
+  : (process.env.LOG_LEVEL ?? (process.env.NODE_ENV === "development" ? "debug" : "info"));
+
+/** LRU domain → site cache max entries */
+export const DOMAIN_CACHE_MAX = LOW_RESOURCE
+  ? parseInt(process.env.DOMAIN_CACHE_MAX ?? "500")
+  : parseInt(process.env.DOMAIN_CACHE_MAX ?? "10000");
+
+/** LRU file path → objectPath cache max entries */
+export const FILE_CACHE_MAX = LOW_RESOURCE
+  ? parseInt(process.env.FILE_CACHE_MAX ?? "2000")
+  : parseInt(process.env.FILE_CACHE_MAX ?? "50000");
+
+/** Analytics buffer flush interval (ms) */
+export const ANALYTICS_FLUSH_INTERVAL_MS = LOW_RESOURCE
+  ? parseInt(process.env.ANALYTICS_FLUSH_INTERVAL_MS ?? "300000")   // 5 minutes
+  : parseInt(process.env.ANALYTICS_FLUSH_INTERVAL_MS ?? "60000");   // 1 minute
+
+/** Federation node health check interval (ms) */
+export const HEALTH_CHECK_INTERVAL_MS = LOW_RESOURCE
+  ? parseInt(process.env.HEALTH_CHECK_INTERVAL_MS ?? "600000")      // 10 minutes
+  : parseInt(process.env.HEALTH_CHECK_INTERVAL_MS ?? "120000");     // 2 minutes
+
+/** Site health monitor interval (ms) */
+export const SITE_HEALTH_INTERVAL_MS = LOW_RESOURCE
+  ? parseInt(process.env.SITE_HEALTH_CHECK_INTERVAL_MS ?? "1800000") // 30 minutes
+  : parseInt(process.env.SITE_HEALTH_CHECK_INTERVAL_MS ?? "600000");  // 10 minutes
+
+/** Global rate limit max requests per minute per IP */
+export const GLOBAL_RATE_LIMIT = LOW_RESOURCE ? 60 : 300;
+
+/** Upload rate limit max per minute per IP */
+export const UPLOAD_RATE_LIMIT = LOW_RESOURCE ? 10 : 60;
+
+/** zlib compression level (1 = fastest/least CPU, 9 = best/most CPU) */
+export const COMPRESSION_LEVEL = LOW_RESOURCE ? 1 : 6;
+
+/** Gossip push interval (ms) */
+export const GOSSIP_INTERVAL_MS = LOW_RESOURCE
+  ? parseInt(process.env.GOSSIP_INTERVAL_MS ?? "600000")  // 10 minutes
+  : parseInt(process.env.GOSSIP_INTERVAL_MS ?? "300000"); // 5 minutes
+
+if (LOW_RESOURCE) {
+  // Log once at startup so operators know the mode is active
+  // Using console directly since the logger may not be initialised yet
+  console.warn(
+    "[config] LOW_RESOURCE=true — running in low-resource mode. " +
+    "DB pool: 5, caches: 500/2K, flush: 5min, health: 10min. " +
+    "All API routes and federation remain fully functional."
+  );
+}

artifacts/api-server/src/middleware/rateLimiter.ts

@@ -2,6 +2,7 @@ import rateLimit from "express-rate-limit";
 import slowDown from "express-slow-down";
 import { getRedisClient } from "../lib/redis";
 import logger from "../lib/logger";
+import { GLOBAL_RATE_LIMIT, UPLOAD_RATE_LIMIT } from "../lib/resourceConfig";
 
 const isProd = process.env.NODE_ENV === "production";
 
@@ -34,10 +35,10 @@ function makeHandler(message: string, code: string) {
   };
 }
 
-// Global limiter — 300 requests / minute per IP
+// Global limiter — 300 requests / minute per IP (60 in LOW_RESOURCE mode)
 export const globalLimiter = rateLimit({
   windowMs: 60_000,
-  max: isProd ? 300 : 10_000,
+  max: isProd ? GLOBAL_RATE_LIMIT : 10_000,
   standardHeaders: "draft-7",
   legacyHeaders: false,
   store,
@@ -58,10 +59,10 @@ export const authLimiter = rateLimit({
   ),
 });
 
-// Upload endpoints — 60 uploads / minute per IP
+// Upload endpoints — 60 uploads / minute per IP (10 in LOW_RESOURCE mode)
 export const uploadLimiter = rateLimit({
   windowMs: 60_000,
-  max: isProd ? 60 : 1_000,
+  max: isProd ? UPLOAD_RATE_LIMIT : 1_000,
   standardHeaders: "draft-7",
   legacyHeaders: false,
   store,

crates/fedhost-proxy/Cargo.toml

@@ -0,0 +1,76 @@
+[package]
+name = "fedhost-proxy"
+version = "0.1.0"
+edition = "2021"
+description = "High-performance reverse proxy for Federated Hosting static site serving"
+license = "MIT"
+repository = "https://github.com/The-No-Hands-company/Federated-Hosting"
+authors = ["The No Hands Company <dev@nohands.company>"]
+
+# This crate is not published to crates.io — it is deployed as a binary
+# alongside the TypeScript API server.
+
+[[bin]]
+name = "fedhost-proxy"
+path = "src/main.rs"
+
+[dependencies]
+# HTTP server
+axum = { version = "0.7", features = ["tokio"] }
+tokio = { version = "1", features = ["full"] }
+tower = "0.4"
+tower-http = { version = "0.5", features = ["compression-gzip", "trace", "timeout"] }
+hyper = { version = "1", features = ["full"] }
+hyper-util = { version = "0.1", features = ["full"] }
+
+# S3 / object storage
+aws-config = { version = "1", features = ["behavior-version-latest"] }
+aws-sdk-s3 = "1"
+
+# PostgreSQL (read-only — domain → siteId lookups)
+tokio-postgres = { version = "0.7", features = ["with-serde_json-1"] }
+deadpool-postgres = "0.12"
+
+# Redis (LRU cache sharing with TypeScript nodes)
+redis = { version = "0.25", features = ["tokio-comp", "connection-manager"] }
+
+# Ed25519 (verify federation signatures — same keypairs as TS node)
+ed25519-dalek = { version = "2", features = ["pkcs8", "pem"] }
+base64 = "0.22"
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# Configuration
+dotenvy = "0.15"
+clap = { version = "4", features = ["derive", "env"] }
+
+# Observability
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+metrics = "0.22"
+metrics-exporter-prometheus = "0.13"
+
+# Utilities
+anyhow = "1"
+thiserror = "1"
+bytes = "1"
+mime_guess = "2"
+sha2 = "0.10"
+hex = "0.4"
+
+[dev-dependencies]
+tokio-test = "0.4"
+axum-test = "0.15"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+strip = true        # strip debug symbols — smaller binary for Pi deployment
+panic = "abort"     # smaller binary, no unwinding
+
+[profile.dev]
+opt-level = 0
+debug = true