post-W7 cleanup

README.md

@@ -13,8 +13,8 @@ UCE is a PHP-inspired server-side runtime that lets you build web pages and hand
 - WebSocket pages can additionally expose `WS(Request& context)`
 - local CLI/admin/test entrypoints can expose `CLI(Request& context)` and are invoked through the Unix CLI socket
 - sub-rendering and components pass structured data through `context.props`
-- nginx can forward normal `.uce` requests and ordinary `.ws.uce` page loads to the FastCGI socket, while real WebSocket upgrade requests for `.ws.uce` endpoints go to the built-in HTTP/WebSocket listener
-- the nginx-published application tree lives under `site/`
+- nginx can forward normal `.uce` requests to the FastCGI socket, while WebSocket upgrade requests for `.uce` endpoints go to the built-in HTTP/WebSocket listener
+- the example application tree lives under `site/`; deployments should publish app files to a normal web root such as `/var/www/html`
 - you can include C++ code as much as you want, but only .uce files called via API functions and entry points will be pre-processed
 - the preprocessor has two jobs:
        - allow for inline HTML within C++ and the use of templating tags inside of that HTML
@@ -45,8 +45,10 @@ The current build expects:
 - `mysql_config`
 - PCRE2 development headers and library (`libpcre2-dev` on Debian / Ubuntu)
 - standard Linux development headers for `dl`, `pthread`, sockets, and backtrace support
+- Wasmtime C API / C++ headers, defaulting to `/opt/wasmtime` or `WASMTIME_HOME`
+- WASI SDK tools, defaulting to `/opt/wasi-sdk` or `WASI_SDK`, for `scripts/build_core_wasm.sh` and unit compilation
 
-SQLite is vendored under `src/3rdparty/sqlite/` and compiled by `scripts/build_linux.sh`; no system SQLite package is required.
+SQLite and miniz are vendored under `src/3rdparty/`; no system SQLite or zlib package is required for those helpers.
 
 The binary is written to:
 
@@ -184,7 +186,7 @@ The runtime keeps the socket lifecycle in-process and exposes a low-boilerplate
 - `ws_send_to(connection_id, message[, binary])`
 - `ws_close([connection_id])`
 
-By default, the WebSocket scope is the current page file, so `ws_send()` queues a message for clients connected to that same `.ws.uce` endpoint.
+By default, the WebSocket scope is the current page file, so `ws_send()` queues a message for clients connected to that same `.uce` endpoint.
 
 Each live WebSocket connection owns a broker-side `DValue` exposed to page code as `context.connection`. Mutations to that tree persist for the life of the socket and are visible on later `WS(Request& context)` calls for the same client.
 
@@ -248,8 +250,8 @@ Representative test pages:
 The intended production shape is:
 
 - nginx serves static files directly
-- nginx forwards `.uce` requests and ordinary `.ws.uce` page loads to the UCE FastCGI Unix socket
-- nginx proxies actual WebSocket upgrade requests for `.ws.uce` endpoints to the runtime's built-in HTTP/WebSocket listener
+- nginx forwards ordinary `.uce` page loads to the UCE FastCGI Unix socket
+- nginx proxies WebSocket upgrade requests for `.uce` endpoints to the runtime's built-in HTTP/WebSocket listener
 - systemd keeps the runtime built, started, and restarted on failure
 
 The repository ships the pieces used for this:
@@ -264,7 +266,7 @@ On a Debian or Ubuntu host, start with the packages needed to build and run UCE
 
 ```bash
 apt update
-apt install -y nginx clang mariadb-client libmariadb-dev libpcre2-dev build-essential
+apt install -y nginx clang mariadb-client libmariadb-dev libpcre2-dev build-essential curl rsync ca-certificates
 ```
 
 The exact package names may vary by distro. The important requirements are:
@@ -274,16 +276,26 @@ The exact package names may vary by distro. The important requirements are:
 - `mysql_config`
 - PCRE2 development headers and library (`libpcre2-dev` on Debian / Ubuntu)
 - normal Linux development headers for threads, sockets, `dl`, and backtrace support
+- Wasmtime C API / C++ headers installed at `/opt/wasmtime` or configured with `WASMTIME_HOME`
+- WASI SDK installed at `/opt/wasi-sdk` or configured with `WASI_SDK`
 
 ### 2. Put the repo on the server
 
 This README assumes the repository lives at:
 
 ```bash
-/Code/uce.openfu.com/uce
+/opt/uce
 ```
 
-That is what the shipped `scripts/systemd/uce.service` file currently uses as its `WorkingDirectory` and build path. If you deploy somewhere else, update that unit file before enabling the service.
+The examples below use that path for the runtime. Publish public application files under the normal web root, for example:
+
+```bash
+cd /opt/uce
+mkdir -p /var/www/html
+rsync -a site/ /var/www/html/
+```
+
+If you deploy somewhere else, update the systemd unit's `WorkingDirectory`, build path, and `ExecStart` path before enabling the service.
 
 ### 3. Configure `/etc/uce/settings.cfg`
 
@@ -304,7 +316,7 @@ FCGI_SOCKET_PATH=/run/uce/fastcgi.sock
 FCGI_PORT=9993
 
 PRECOMPILE_FILES_IN=
-SITE_DIRECTORY=site
+SITE_DIRECTORY=/var/www/html
 PROACTIVE_COMPILE_CHECK_INTERVAL=60
 
 WORKER_COUNT=4
@@ -328,7 +340,7 @@ HTTP_PORT=8080
 
 Proactive compilation settings:
 
-- `SITE_DIRECTORY=site` tells the runtime which tree to scan on startup for `.uce` files when `PRECOMPILE_FILES_IN` is left empty.
+- `SITE_DIRECTORY=/var/www/html` tells the runtime which public web tree to scan on startup for `.uce` files when `PRECOMPILE_FILES_IN` is left empty.
 - `PRECOMPILE_FILES_IN=` can override that startup scan root with a different absolute or runtime-relative directory.
 - `PROACTIVE_COMPILE_CHECK_INTERVAL=60` controls how often the low-priority background compiler rechecks known `.uce` files for stale or missing wasm modules.
 
@@ -395,12 +407,14 @@ That script:
 - writes Debian maintainer scripts for systemd reload/enable handling
 - follows a more PHP-like/FHS deployment shape with immutable runtime files under `/usr/lib`, config under `/etc`, cache/state under `/var`, and the FastCGI socket under `/run/uce/`
 
-### 5. Configure nginx for `.uce` and `.ws.uce`
+### 5. Configure nginx for `.uce` and WebSocket upgrades
 
-You need two nginx paths for `.ws.uce` endpoints:
+Any `.uce` unit can expose `WS(Request& context)`. WebSocket upgrade requests for `.uce` paths should be routed to the runtime's HTTP/WebSocket listener.
 
-- FastCGI for ordinary `.uce` requests and plain `.ws.uce` page renders
-- HTTP proxying only for actual WebSocket upgrade traffic on `.ws.uce` endpoints
+You need two transport paths for `.uce` endpoints:
+
+- FastCGI for ordinary `.uce` page renders
+- HTTP proxying only for WebSocket upgrade traffic on `.uce` endpoints
 
 If you use WebSockets, add this `map` in the nginx `http` block:
 
@@ -417,7 +431,7 @@ Then use a server block along these lines:
 server {
 	listen 80;
 	server_name example.com;
-	root /Code/uce.openfu.com/uce/site;
+	root /var/www/html;
 
 	index index.uce index.html;
 
@@ -426,16 +440,6 @@ server {
 	}
 
 	location ~ \.uce$ {
-		include fastcgi_params;
-		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-		fastcgi_param DOCUMENT_ROOT $document_root;
-		fastcgi_param SCRIPT_NAME $fastcgi_script_name;
-		fastcgi_param DOCUMENT_URI $uri;
-		fastcgi_param REQUEST_URI $request_uri;
-		fastcgi_pass unix:/run/uce/fastcgi.sock;
-	}
-
-	location ~ \.ws\.uce$ {
 		error_page 418 = @uce_websocket;
 		if ($http_upgrade = "websocket") {
 			return 418;
@@ -453,7 +457,6 @@ server {
 	location @uce_websocket {
 		proxy_http_version 1.1;
 		proxy_set_header Host $host;
-		proxy_set_header X-Real-IP $remote_addr;
 		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 		proxy_set_header X-Forwarded-Proto $scheme;
 		proxy_set_header Upgrade $http_upgrade;
@@ -465,19 +468,19 @@ server {
 
 Important details:
 
-- `.ws.uce` must be matched before the more general `.uce` rule
 - `fastcgi_pass` should point at the same socket path as `FCGI_SOCKET_PATH`
 - `proxy_pass` should point at the runtime's `HTTP_PORT`
-- ordinary `GET /page.ws.uce` page renders should stay on FastCGI
-- only upgrade requests for `/page.ws.uce` should go through the HTTP/WebSocket listener
-- `SCRIPT_FILENAME` should resolve to the actual `.uce` file on disk
+- ordinary `GET /page.uce` page renders should stay on FastCGI
+- only upgrade requests for `/page.uce` should go through the HTTP/WebSocket listener
+- `SCRIPT_FILENAME` should resolve to the requested `.uce` file on disk
 - `proxy_http_version 1.1` and the `Upgrade` / `Connection` headers are required for WebSockets
+- socket-capable pages are ordinary `.uce` units; route client WebSocket upgrade requests to the HTTP/WebSocket listener
 
-The `location /` block only serves files from `site/`. If your app uses a front-controller pattern such as routing everything through `/index.uce`, change that block accordingly.
+The `location /` block only serves files from `/var/www/html`. If your app uses a front-controller pattern such as routing everything through `/index.uce`, change that block accordingly.
 
 ### 6. Think about document root and private files
 
-Point nginx at `site/`, not the repository root. The repo still contains source, scripts, packaging files, and operational assets that are not meant to be public.
+Point nginx at `/var/www/html`, not the runtime repository root. The repo still contains source, scripts, packaging files, and operational assets that are not meant to be public.
 
 At minimum, explicitly block internal directories that should never be served directly. For example:
 
@@ -487,7 +490,7 @@ location ~ ^/(src|scripts|etc|bin|work|dist|pkg)/ {
 }
 ```
 
-If nginx is rooted at `site/`, most of those paths will not be reachable anyway, which is the preferred setup.
+If nginx is rooted at `/var/www/html`, most of those paths will not be reachable anyway, which is the preferred setup.
 
 ### 7. Reload nginx and verify the deployment
 
@@ -506,7 +509,7 @@ curl -i http://127.0.0.1/test/index.uce
 curl -i http://127.0.0.1/doc/index.uce
 ```
 
-If WebSockets are enabled, also verify a `.ws.uce` endpoint through nginx rather than talking to the runtime directly.
+If WebSockets are enabled, also verify a `.uce` endpoint that defines `WS(Request& context)` through nginx rather than talking to the runtime directly.
 
 ### 8. Troubleshooting
 
@@ -515,7 +518,7 @@ Common failure modes:
 - `502 Bad Gateway`
   Usually means `uce.service` is down, the Unix socket path does not match, or the request crashed before sending a valid response.
 - WebSocket upgrade fails
-  Check that nginx is routing `.ws.uce` to `proxy_pass`, not `fastcgi_pass`, and that `HTTP_PORT` is reachable on localhost.
+  Check that nginx is routing WebSocket upgrade requests to `proxy_pass`, not `fastcgi_pass`, and that `HTTP_PORT` is reachable on localhost.
 - Requests compile but immediately crash
   Check `journalctl -u uce.service`. Generated units carry an ABI metadata sidecar and should be recompiled automatically after runtime ABI changes, but clearing stale artifacts under `BIN_DIRECTORY` is still a useful last-resort recovery step if the cache has been damaged manually.
 - nginx serves raw source or internal files