Phone UI and touch precision overhaul, proxy fixes, Orbital Uplink, four new maps
Phone panels (reviewed + QA'd, matrix of 22 layouts with real taps/bounding boxes): - selected-tower action bar over the board (Upgrade/Sell/Target/close), info panel updated in place so taps are never lost, scrollable palette for 7+ towers, overlays with pinned footers (Help "Got it", Play solo, Join always visible), tappable room chip to invite, reduced-motion/contrast/forced-colors fixes, paused state, partner cursor labels, bigger level pips and owner flags - touch input rewritten around "pointerdown commits nothing": pinch never builds, 10px tap slop, palm-proof pinch, long-press pings with any tool armed, nudge arrows for precise placement, hotkey repeat guard, proportional wheel zoom - new e2e: select/sell, info-panel stability, UI states, touch precision; camera unit tests Proxy/server (reproduced against real nginx 1.26 with NPM v2.16 config): - Origin check works when the proxy drops a non-default port, TRUSTED_PROXIES for proxies on global IPv6/CGNAT addresses, service worker no longer serves nginx's 502 page, DEPLOY.md corrected (NPM default read timeout is 90 s, Advanced-tab limits, path-prefix, cookie size, per-IP cap behaviour) Content: - Orbital Uplink: 4-level endgame tower (450 + 500/800/1200 credits): piercing armour-ignoring beam, blast and lingering slow, ground+air, range 11-14; glyph, beam effect, sound, help text, unit tests - Maps: The Canyon, Archipelago, Fortress, Pinwheel (7 maps total) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8
This commit is contained in:
parent
dad0382e10
commit
a5bd09d505
22 changed files with 2423 additions and 405 deletions
249
docs/DEPLOY.md
249
docs/DEPLOY.md
|
|
@ -8,13 +8,25 @@ the co-op rooms. There is no database and no build step; games live in memory (a
|
|||
◀──wss── (HOST=::, IPv4 + IPv6)
|
||||
```
|
||||
|
||||
What was actually run while writing this: the server and its test suite (Node 20.20.2 and 24.21), the real
|
||||
`node server/index.js` over IPv4 and IPv6 on loopback (`curl`, a two-player WebSocket session, `SIGTERM` exit 0), the
|
||||
IPv6-disabled case in a throwaway network namespace, and `systemd-analyze verify` on the unit (syntax only). The
|
||||
proxy behaviour was only *simulated* by sending the headers a proxy would send (`Host`, `X-Forwarded-For`,
|
||||
`X-Forwarded-Host`, `Origin`) straight to the server. **Never run here:** nginx Proxy Manager or any nginx, a started
|
||||
systemd unit, a Proxmox LXC, a real browser or phone. Everything about NPM below is what its documented UI and
|
||||
nginx's behaviour lead one to expect; labels differ between NPM versions, so check each step against your version.
|
||||
What was actually run while writing and re-checking this:
|
||||
|
||||
* The server and its test suite (Node 20.20.2 and 24.21), the real `node server/index.js` over IPv4 and IPv6 on loopback
|
||||
(`curl`, two-player WebSocket sessions, `SIGTERM` exit 0), the IPv6-disabled case in a throwaway network namespace,
|
||||
and `systemd-analyze verify` on the unit (syntax only).
|
||||
* **A real nginx 1.26.3** (the Debian 13 package, unpacked without root and run in a private network namespace) loaded
|
||||
with the server and location blocks that **nginx Proxy Manager v2.16.0** renders: its own `nginx.conf` (timeouts,
|
||||
`real_ip`, headers), `proxy.conf` and the proxy-host and custom-location templates, taken from the NPM v2.16.0 source
|
||||
and filled in by hand. Behind it ran the real game server, headless Chromium (page, service worker, co-op lobby, the
|
||||
e2e scenarios over https), `curl` and raw WebSocket clients, with extra loopback addresses acting as distinct client
|
||||
and proxy addresses (`203.0.113.x`, `2001:db8::x`, `192.168.77.9`). Everything marked **observed** below comes from
|
||||
that setup.
|
||||
* NPM's UI labels (Details / Custom Locations / SSL tabs, "Websockets Support", "Cache Assets", "Forward Hostname / IP",
|
||||
the gear icon for the Advanced box) and its path-prefix handling were **read from the v2.16.0 source**
|
||||
(`frontend/src/...`, `backend/internal/nginx.js`), not clicked through. Those are marked **from source**.
|
||||
|
||||
**Never run:** the NPM application itself (its UI, its Docker image, its database), NPM versions other than 2.16.0,
|
||||
Let's Encrypt, NPM in Docker with published ports (see "Client addresses" in section 4), a real phone, a Proxmox LXC, a
|
||||
started systemd unit, a git deploy key. Labels differ between NPM versions, so check each step against yours.
|
||||
|
||||
## 1. Requirements
|
||||
|
||||
|
|
@ -37,7 +49,9 @@ useradd --system --home-dir /opt/netwall --shell /usr/sbin/nologin netwall
|
|||
|
||||
# copy the project to /opt/netwall (from your workstation, for example):
|
||||
# rsync -a --exclude node_modules --exclude test --exclude .git ./ root@<lxc>:/opt/netwall/
|
||||
# it needs server/, public/, package.json, package-lock.json (docs/ and deploy/ are optional)
|
||||
# it needs server/, public/, package.json, package-lock.json and deploy/ (for the unit file in section 3; docs/ is optional)
|
||||
# or clone it there: `git clone <repository url> /opt/netwall`. That works from inside the LXC only if the LXC can read the
|
||||
# repository: a private one needs an SSH key on the LXC that the git server knows (a read-only "deploy key"); see the README.
|
||||
cd /opt/netwall
|
||||
npm install --omit=dev # only "ws"; `npm ci --omit=dev` also works and follows the lockfile exactly
|
||||
chown -R root:root /opt/netwall # the service user only needs read access
|
||||
|
|
@ -78,8 +92,9 @@ Environment variables, read when the server is started directly (`node server/in
|
|||
|---|---|---|
|
||||
| `PORT` | `8080` | TCP port. `0` picks a free one (the banner prints the real port). |
|
||||
| `HOST` | `::` | Address to bind. `::` is **one dual-stack socket serving IPv4 and IPv6** (`ipv6Only:false`). `0.0.0.0` = IPv4 only. `127.0.0.1` = this container only. Any explicit address is used as given. |
|
||||
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Host` only when the TCP peer is loopback, RFC1918 (`10/8`, `172.16/12`, `192.168/16`), `fc00::/7` or link-local. `1` (also `true`, `yes`, `on`): always believe them. `0` (also `false`, `no`, `off`): never. |
|
||||
| `ALLOWED_ORIGINS` | empty | Comma separated list of extra origins allowed to open the WebSocket, for example `https://game.example.com,https://play.example.org` (list every public name if the game has more than one). See "Origin check". |
|
||||
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Host` (and the stripped-port rule of the "Origin check") only when the TCP peer is loopback, RFC1918 (`10/8`, `172.16/12`, `192.168/16`), `fc00::/7` or link-local, **or is listed in `TRUSTED_PROXIES`**. `1` (also `true`, `yes`, `on`): always believe them, from any peer (then firewall the port). `0` (also `false`, `no`, `off`): never. |
|
||||
| `TRUSTED_PROXIES` | empty | Comma separated IPs and CIDRs (IPv4 or IPv6) that `TRUST_PROXY=auto` believes **in addition to** the private ranges above, for example `100.64.0.0/10,2001:db8::6`. Needed when your proxy reaches the game from an address the built-in list does not call private: a global IPv6 address, Tailscale / CGNAT (`100.64.0.0/10`) or any other routable one. Ignored when `TRUST_PROXY` is `1` or `0`. A malformed entry stops the start-up with a message. See "Client addresses". |
|
||||
| `ALLOWED_ORIGINS` | empty | Comma separated list of extra origins allowed to open the WebSocket, for example `https://game.example.com,https://play.example.org` (list every public name if the game has more than one). **Include the port when it is not 80/443**: `https://game.example.com:8443`. See "Origin check". |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open WebSockets per client IP; more get HTTP `429` on the upgrade. `0` disables the cap. |
|
||||
| `GRACE_MS` | `60000` | How long a disconnected player keeps their slot (so a phone can come back after a screen lock or a network switch). |
|
||||
|
||||
|
|
@ -95,20 +110,37 @@ What the server does, relevant to a proxy setup:
|
|||
it comes from `X-Forwarded-For` (else `X-Real-IP`); otherwise it is the TCP peer. From `X-Forwarded-For` the server
|
||||
takes the **rightmost entry that is not a private address**: proxies such as NPM *append* the address they saw to
|
||||
whatever header the client sent, so the entries further left are the client's own claim and are never believed (a
|
||||
chain that is private all the way gives its rightmost entry; a client with a private LAN address cannot be told
|
||||
apart from your own proxy hops, so it can still choose its own address). IPv4-mapped IPv6 peers (`::ffff:a.b.c.d`) are shown
|
||||
as plain IPv4. `X-Forwarded-Proto` is never used.
|
||||
chain that is private all the way gives its rightmost entry). IPv4-mapped IPv6 peers (`::ffff:a.b.c.d`) are shown
|
||||
as plain IPv4. `X-Forwarded-Proto` is never used. See "Client addresses" below for what this does and does not protect
|
||||
when the proxy is nginx Proxy Manager.
|
||||
* **Player ids.** A player's id (`pid`, kept in the browser's session storage) is what lets a browser take its slot
|
||||
back after a disconnect, so the server only ever sends it to its owner; the other player is shown under an opaque,
|
||||
stable alias.
|
||||
* **Keep-alive.** Every 25 s the server sends a WebSocket protocol ping to each socket and terminates a socket that did
|
||||
not answer the previous one (browsers answer automatically). The ping traffic also keeps nginx's `proxy_read_timeout`
|
||||
(default 60 s) from firing on an idle but healthy game. A terminated player stays in the room for `GRACE_MS`.
|
||||
* **Keep-alive and dead peers.** Every 25 s the server sends a WebSocket protocol ping to each socket and terminates a
|
||||
socket that did not answer the previous one (browsers answer automatically), so a phone that silently lost the
|
||||
network is dropped after 25 to 50 s (observed through nginx: first ping at 24.8 s, socket closed at 49.8 s). A
|
||||
terminated player stays in the room for `GRACE_MS`. The pings are for finding dead peers; they are **not** what keeps a
|
||||
proxy's idle timer quiet: a joined game receives about 20 snapshots a second, also while paused, so nginx never sees
|
||||
the connection idle. Observed: a paused two-player room behind a 20 s `proxy_read_timeout` stayed connected for
|
||||
60 s (three timeouts' worth) with no reconnect, at 20.5 frames/s per browser. nginx Proxy Manager's own default is 90 s
|
||||
(`proxy_connect_timeout`, `proxy_send_timeout`, `proxy_read_timeout` and `keepalive_timeout` in its v2.16.0
|
||||
`nginx.conf`), so no timeout setting is needed for the game. A socket that never joins is closed by the server after
|
||||
10 s, whatever the proxy does.
|
||||
* **Origin check** (WebSocket upgrade only, path `/ws`). A request without `Origin` is allowed (non-browser clients).
|
||||
Otherwise the origin host must equal the `Host` header, **or** the first entry of `X-Forwarded-Host` (only from a
|
||||
trusted proxy), **or** be listed in `ALLOWED_ORIGINS`. Comparison is on lower-case `host[:port]` with the scheme
|
||||
ignored and ports 80/443 treated as "no port" (so listing `https://game.example.com` also admits
|
||||
`http://game.example.com`). Everything else gets `403`; the reason is logged.
|
||||
trusted proxy), **or** (trusted proxy only) the `Host` header has **no port** and the origin has the same host name on
|
||||
any port, **or** be listed in `ALLOWED_ORIGINS`. Comparison is on lower-case `host[:port]` with the scheme ignored
|
||||
and ports 80/443 treated as "no port" (so listing `https://game.example.com` also admits `http://game.example.com`,
|
||||
but not `https://game.example.com:8443`). Everything else gets `403`; the reason is logged.
|
||||
The "no port" rule exists because nginx's `proxy_set_header Host $host` (which nginx Proxy Manager uses) **drops the
|
||||
port**: published on `https://game.example.com:8443`, the browser's Origin is `https://game.example.com:8443` but the
|
||||
server sees `Host: game.example.com`. Observed before the fix: 403 for both http and https on a non-default port
|
||||
(`refused websocket ... Origin "https://highport.test:8332" does not match Host "highport.test"`), and the same
|
||||
proxy host worked on 80/443; after it, both join. A browser talking to the server directly on its default
|
||||
port 8080 (or any port other than 80/443) always sends that port in `Host`, so direct connections are still matched
|
||||
exactly (observed: Origin `:9999` against Host `127.0.0.1:8331` is refused), and a different host name is still
|
||||
refused (observed through the proxy). The one exception is a server you run on `PORT=80` or `443` itself: a direct
|
||||
connection from a private address then also has a port-less `Host` and gets the same-host-name rule (other host names are still refused).
|
||||
* **Path prefix.** The server only knows `/ws` and `/`; the browser builds the socket URL relative to the page, so a
|
||||
proxy that strips a prefix works (section 7).
|
||||
* `GET /healthz` (and `HEAD`) returns `200 ok`. Static files are only served from `public/`, with
|
||||
|
|
@ -119,9 +151,41 @@ What the server does, relevant to a proxy setup:
|
|||
* **Shutdown.** `SIGTERM`/`SIGINT`: all sockets are closed with code 1001, the process exits 0 (within about a
|
||||
second, forced after 5 s). Running games are lost; clients that reconnect are told the room no longer exists.
|
||||
|
||||
### Client addresses (per-IP cap, log) behind nginx Proxy Manager
|
||||
|
||||
`MAX_CONN_PER_IP` (default 40 open WebSockets per address) counts the client address the server works out: from
|
||||
`X-Forwarded-For` / `X-Real-IP` when the TCP peer is a trusted proxy, otherwise the peer itself. All of the following
|
||||
was **observed** against nginx 1.26.3 with NPM v2.16.0's configuration, with the cap set to 3 to make it visible:
|
||||
|
||||
* **A proxy on an address the built-in list does not call private** (a global IPv6 address, Tailscale / CGNAT
|
||||
`100.64.0.0/10`; the built-in check says "not private" for `2001:db8::6` and `100.64.1.1`): with
|
||||
`TRUST_PROXY=auto` the server believes no forwarded header. Three client addresses behind a proxy at `2001:db8::6`
|
||||
got 3 sockets in total and `429` for the rest, and the log said `from 2001:db8::6` for everybody; with
|
||||
`TRUSTED_PROXIES=2001:db8::6` each client address got its own budget (2 joined each, 6 in total) and the log named
|
||||
`203.0.113.5`, `.6`, `.7`. `TRUST_PROXY=1` does the same without a list but trusts every peer, so firewall port 8080
|
||||
to the proxy if you use it. Symptom of the problem: every log line says `from <the proxy>`, and a few players
|
||||
exhaust the cap for everyone. The same untrusted-proxy case also ignores `X-Forwarded-Host` and the stripped-port
|
||||
rule of the Origin check; the 403 line in the log then says `this connection is not from a trusted proxy`.
|
||||
* **Public clients cannot fake an address.** A public client sending its own `X-Forwarded-For` and `X-Real-IP`
|
||||
(`198.51.100.1`, `.2`) was still counted as its real address (`203.0.113.5`): 3 sockets joined, 2 refused.
|
||||
* **Clients on a private (LAN or VPN) address can choose any address.** NPM's `nginx.conf` has
|
||||
`set_real_ip_from 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; real_ip_header X-Real-IP;`, so when the connection to NPM
|
||||
comes from such an address, nginx replaces its idea of the client address with the client's own `X-Real-IP` header
|
||||
*before* it builds the forwarded headers. Eight sockets from one LAN address (`192.168.77.9`), each sending a
|
||||
different `X-Real-IP`, all joined and were logged as `198.51.100.1` to `.8` although the cap was 3; five sockets from the
|
||||
same LAN address without the header were capped at 3. The cap is therefore a guard against accidents and against
|
||||
public abuse, **not** against someone on your own LAN: rely on the firewall and on who is on the network. Nothing else
|
||||
in the game depends on the client address (it only affects the cap and the log).
|
||||
* **LAN players that nginx sees as one address share one budget.** Players whose connections reach nginx from the same
|
||||
address (a household behind one public IP, or a router in front of the proxy) count together, which is fine at 40
|
||||
sockets (the game uses one socket per player). **Not run:** NPM in Docker with published ports and the default bridge
|
||||
network, where nginx may see every LAN client as the Docker gateway address. If all your LAN players get `429`
|
||||
there, raise `MAX_CONN_PER_IP`, or set it to `0` for a private game.
|
||||
|
||||
## 5. nginx Proxy Manager (NPM)
|
||||
|
||||
In NPM, **Hosts > Proxy Hosts > Add Proxy Host**.
|
||||
In NPM, **Hosts > Proxy Hosts > Add Proxy Host** (tab names and labels as in the v2.16.0 source: *Details*, *Custom
|
||||
Locations*, *SSL*, and the gear icon at the right end of the tab row for the Advanced box).
|
||||
|
||||
**Details tab**
|
||||
|
||||
|
|
@ -129,39 +193,77 @@ In NPM, **Hosts > Proxy Hosts > Add Proxy Host**.
|
|||
|---|---|
|
||||
| Domain Names | `game.example.com` |
|
||||
| Scheme | `http` |
|
||||
| Forward Hostname / IP | the LXC's IP address (for example `192.168.1.50`) or a name NPM can resolve |
|
||||
| Forward Hostname / IP | the LXC's IP address (for example `192.168.1.50`) or a name NPM can resolve. Not `127.0.0.1` / `localhost` when NPM runs in its own container or on another machine: that would be NPM itself |
|
||||
| Forward Port | `8080` |
|
||||
| Cache Assets | **off** (the game files must revalidate; the server already sends `no-cache`) |
|
||||
| Block Common Exploits | optional, can stay on |
|
||||
| **Websockets Support** | **on** (required: it adds the `Upgrade` / `Connection` headers and HTTP/1.1 to the upstream) |
|
||||
| **Websockets Support** | **on** (required: it adds the `Upgrade` / `Connection` headers and HTTP/1.1 to the upstream). Observed with it off: the page loads, the browser's WebSocket gets HTTP `426`, and the lobby only says "Could not reach the game server." |
|
||||
|
||||
**Custom Locations tab**: leave empty (only needed for a path prefix, section 7).
|
||||
|
||||
**SSL tab**: SSL Certificate = *Request a new SSL Certificate* (Let's Encrypt), then switch on **Force SSL** and
|
||||
**HTTP/2 Support** (HSTS is optional), agree to the terms, Save. Browsers fall back to HTTP/1.1 for the WebSocket;
|
||||
that is normal.
|
||||
that is normal. (The Let's Encrypt request itself was not run; it needs the name to resolve to your proxy and ports
|
||||
80/443 reachable from the internet, see NPM's own documentation.)
|
||||
|
||||
**Advanced tab** (Custom Nginx Configuration): paste
|
||||
**Advanced tab** (gear icon, *Custom Nginx Configuration*): nothing is required. In particular no
|
||||
`proxy_read_timeout` / `proxy_send_timeout` is needed: NPM's default is 90 s, and a joined game never goes quiet
|
||||
(see "Keep-alive and dead peers" in section 4). Save, then open `https://game.example.com/`.
|
||||
|
||||
```nginx
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
```
|
||||
### The Host header, ports other than 443, and what the Advanced tab can and cannot do
|
||||
|
||||
Not strictly needed (the server pings every 25 s), but it makes a long-idle game survive proxies and middleboxes
|
||||
with short idle timers. Save, then open `https://game.example.com/`.
|
||||
What NPM v2.16.0's `proxy.conf` sends upstream is `Host $host`, `X-Forwarded-Scheme`, `X-Forwarded-Proto`,
|
||||
`X-Forwarded-For $proxy_add_x_forwarded_for` and `X-Real-IP`, plus `Upgrade` / `Connection` when Websockets Support is
|
||||
on. Observed with an echo server behind the rendered config: `host` is the public name **without a port**, and there is
|
||||
**no `X-Forwarded-Host` and no `X-Forwarded-Port`**. The browser's `Origin` and that `Host` match on 80/443, so
|
||||
nothing needs configuring there.
|
||||
|
||||
NPM is expected to pass the original `Host` header through unchanged (not verified here); then the browser's `Origin`
|
||||
and the `Host` the server sees match and no configuration is needed. If the server log shows
|
||||
`refused websocket ... does not match Host` (HTTP 403 on the upgrade), or if you set `Host` yourself in a custom
|
||||
config, either make the proxy send `X-Forwarded-Host` with the public name, or set
|
||||
`ALLOWED_ORIGINS=https://game.example.com`.
|
||||
* **Public port other than 80/443** (for example NPM published on `8443`, or Docker `-p 8443:443`): `$host` drops the
|
||||
port, so Origin `https://game.example.com:8443` meets `Host: game.example.com`. Older versions of the server answered
|
||||
`403` (observed: both `http://highport.test:8330` and `https://highport.test:8332` failed with `HTTP 403`; the same
|
||||
host on 80/443 worked). The current server accepts the same host name on any port **when the connection comes from a
|
||||
trusted proxy** (private address, or one listed in `TRUSTED_PROXIES`); observed: both now join, and a different host
|
||||
name or a direct connection with a mismatching port is still refused. If your proxy is **not** trusted (a global IPv6 or
|
||||
Tailscale address and no `TRUSTED_PROXIES`, or `TRUST_PROXY=0`), the log says `this connection is not from a trusted
|
||||
proxy`: list the proxy in `TRUSTED_PROXIES`, or set `ALLOWED_ORIGINS=https://game.example.com:8443` **with the port**
|
||||
(observed: an entry without the port does not match an origin with one).
|
||||
* **You cannot add `X-Forwarded-Host` (or change `Host`) from the Advanced tab for the default location.** Observed:
|
||||
`proxy_set_header X-Forwarded-Host $host;` and `proxy_set_header Host an.internal.name;` typed into the Advanced box
|
||||
were silently ignored (the upstream still saw `Host: <public name>` and no `X-Forwarded-Host`), because NPM renders the
|
||||
Advanced text at the `server {}` level and its own `location /` sets its own `proxy_set_header` lines, so nginx
|
||||
inherits none of the server-level ones. The same two lines inside a *custom location's* gear box do take effect
|
||||
(observed). From source: an Advanced box that contains its own `location / {` replaces NPM's default location
|
||||
completely, and then you must repeat every proxy header and the `Upgrade` / `Connection` pair yourself.
|
||||
So for an NPM user the one fix that always works is `ALLOWED_ORIGINS=https://game.example.com` (with the port if it
|
||||
is not 443). `X-Forwarded-Host` is for hand-written nginx: observed with a hand-written `location /` that sets
|
||||
`Host an.internal.name` and `X-Forwarded-Host $host`, `TRUST_PROXY=auto` joined, `TRUST_PROXY=0` got `403`, and
|
||||
`TRUST_PROXY=0` with `ALLOWED_ORIGINS=http://rw2.test` joined again.
|
||||
|
||||
Optional, in the same Advanced box, to compress text for phones on mobile data (the Node server does not):
|
||||
Optional, in the Advanced box, to compress text for phones on mobile data (the Node server does not; NPM's own
|
||||
`gzip on` only covers `text/html` by default, observed):
|
||||
|
||||
```nginx
|
||||
gzip on;
|
||||
gzip_types text/css text/javascript application/javascript application/json image/svg+xml;
|
||||
gzip_types text/css text/javascript application/javascript application/json application/manifest+json image/svg+xml;
|
||||
```
|
||||
|
||||
Observed with this list: `/`, `js/*.js`, `css/style.css`, `sw.js`, `icons/icon.svg`, `assets/music/tracks.json` and
|
||||
`manifest.webmanifest` come back `Content-Encoding: gzip`; the PNG icons and mp3 files are left alone.
|
||||
|
||||
Optional, if **co-op never connects but the page loads** and the browser's developer tools show the `/ws` request
|
||||
answered `400 Request Header Or Cookie Too Large`: another application on the same parent domain has set big cookies,
|
||||
and the browser sends them to the game too. nginx's default `large_client_header_buffers 4 8k` refuses a single header
|
||||
line above 8 KB (NPM leaves that default). Observed with an 8300-byte cookie: `400` on HTTP/1.1 requests and on the
|
||||
WebSocket upgrade, while the page itself still loaded over HTTP/2 (`200`); up to about 7.8 KB everything worked. Put
|
||||
|
||||
```nginx
|
||||
large_client_header_buffers 4 16k;
|
||||
```
|
||||
|
||||
in the Advanced box (observed: cookies up to 16000 bytes then pass, upgrade included). Do not expect more: the Node
|
||||
server itself refuses request headers above about 16 KB with `431` (observed at 16.3 KB), so beyond that clear the
|
||||
cookies or serve the game from a name outside the cookie's domain. The game sets no cookies of its own.
|
||||
|
||||
## 6. Dual stack (IPv4 + IPv6)
|
||||
|
||||
* **The app side is automatic.** `HOST=::` (the default) is a single dual-stack socket: IPv4 clients arrive as
|
||||
|
|
@ -195,9 +297,10 @@ gzip_types text/css text/javascript application/javascript application/json imag
|
|||
```
|
||||
|
||||
`systemctl enable --now nftables`. The Proxmox firewall (Datacenter / Node / CT > Firewall) can do the same.
|
||||
`TRUST_PROXY=auto` is meant for exactly this setup: only private-range peers (the proxy) are believed. If the port
|
||||
is reachable by other LAN machines they could forge `X-Forwarded-For`; the effect is limited to the per-IP cap
|
||||
and the log.
|
||||
`TRUST_PROXY=auto` is meant for exactly this setup: only private-range peers (the proxy) are believed, plus the
|
||||
addresses in `TRUSTED_PROXIES` if your proxy reaches the LXC over a global IPv6, Tailscale / `100.64.0.0/10` or other
|
||||
routable address. If the port is reachable by other LAN machines they could forge `X-Forwarded-For`; the effect is
|
||||
limited to the per-IP cap and the log (and see "Client addresses" for what NPM lets LAN clients do on its own).
|
||||
* **IPv6 disabled in the container.** If IPv6 is switched off by sysctl (`net.ipv6.conf.all.disable_ipv6=1`) the
|
||||
`::` socket still binds and still serves IPv4 (tested in a throwaway Linux network namespace with
|
||||
`disable_ipv6=1`, not in an LXC). Only a kernel without IPv6 at all fails to bind `::`
|
||||
|
|
@ -210,11 +313,39 @@ gzip_types text/css text/javascript application/javascript application/json imag
|
|||
The client never uses absolute URLs: it opens `new URL('ws', location.href)`, so at `https://example.com/netwall/`
|
||||
it connects to `wss://example.com/netwall/ws`. The proxy must **strip the prefix** so the server sees `/` and `/ws`,
|
||||
and the page must be opened **with the trailing slash** (`/netwall/`, not `/netwall`, or the relative URLs resolve to
|
||||
the wrong place). The behaviour you need is this nginx block (a trailing slash on `proxy_pass` replaces the matched
|
||||
prefix):
|
||||
the wrong place; nginx itself redirects `/netwall` to `/netwall/` for the locations below, observed). The simpler route
|
||||
is a dedicated sub-domain (`game.example.com`), which needs none of this. Origin check: the browser's `Origin` is
|
||||
`https://example.com` and `Host` is `example.com`, so it passes unchanged.
|
||||
|
||||
**Way 1, in the NPM UI: the Custom Locations tab of the proxy host.** Add a location with
|
||||
|
||||
| Field | Value | Why |
|
||||
|---|---|---|
|
||||
| Location | `/netwall/` | **with the trailing slash** |
|
||||
| Scheme / Forward Port | `http` / `8080` | |
|
||||
| Forward Hostname / IP | `192.168.1.50/` | **with a trailing slash after the address**: NPM turns everything after the first `/` into the path it puts on `proxy_pass`, so this renders `proxy_pass http://192.168.1.50:8080/;`, and that trailing `/` is what strips the `/netwall/` prefix |
|
||||
|
||||
and keep **Websockets Support** on in the Details tab (NPM copies it into each location). The Details tab still needs a
|
||||
forward target for the host's own `/`; point it at whatever else the name serves.
|
||||
What was run and what was not: NPM's `_location.conf` template, filled in the way its backend does it for exactly these
|
||||
values, was run in nginx (observed: `/netwall/healthz` `200`, `/netwall` answered `301` to `/netwall/`, a WebSocket
|
||||
join through `wss://.../netwall/ws`, and the repo's e2e smoke scenario and two-browser co-op scenario, invite link and
|
||||
reconnect included, over https at `https://.../netwall/`). That a slash typed into the
|
||||
Forward Hostname field is split into the forward path is **from source** (`backend/internal/nginx.js`
|
||||
`renderLocations` in v2.16.0, and the field's own placeholder there, `eg: 10.0.0.1/path/`); the UI itself was not clicked.
|
||||
Two near misses, both observed, that make this fail:
|
||||
|
||||
* Location `/netwall` **without** the trailing slash and a forward target ending in `/`: the page and its files load,
|
||||
but `/netwall/healthz` and `/netwall/ws` are `404` (the upstream sees `//ws`), so co-op reports "Could not reach the
|
||||
game server" (`WebSocket ... Unexpected response code: 404`).
|
||||
* Forward Hostname `192.168.1.50` **without** the slash: nothing is stripped, so every `/netwall/...` request is `404`.
|
||||
|
||||
**Way 2: the host's Advanced tab** (gear icon). Paste this block; it adds its own location next to NPM's default one,
|
||||
so the host's Details tab still needs *some* forward target. Observed working verbatim (the proxy address replaced by a
|
||||
local one): `/netwall/healthz` `200`, `/netwall` `301` to `/netwall/`, `manifest.webmanifest` `200`, a music file with a
|
||||
`Range` header `206`, a WebSocket join through `wss://.../netwall/ws`, and the e2e smoke and co-op scenarios over https.
|
||||
|
||||
```nginx
|
||||
location = /netwall { return 301 /netwall/; }
|
||||
location /netwall/ {
|
||||
proxy_pass http://192.168.1.50:8080/;
|
||||
proxy_http_version 1.1;
|
||||
|
|
@ -223,15 +354,12 @@ location /netwall/ {
|
|||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
```
|
||||
|
||||
In NPM the dialog differs between versions (Proxy Host > **Custom locations** tab, or the Advanced tab of a host).
|
||||
Whichever you use, the result must be the block above; check with `curl -i https://example.com/netwall/healthz`
|
||||
(expect `200 ok`). The simpler route is a dedicated sub-domain (`game.example.com`), which needs none of this.
|
||||
Origin check: the browser's `Origin` is `https://example.com` and `Host` is `example.com`, so it passes unchanged.
|
||||
(An earlier version of this guide also had `location = /netwall { return 301 /netwall/; }` in front: redundant, because
|
||||
nginx already answers `/netwall` with `301` to `/netwall/` for a prefix location ending in a slash; observed.) Check with
|
||||
`curl -i https://example.com/netwall/healthz` (expect `200 ok`).
|
||||
|
||||
## 8. Verify
|
||||
|
||||
|
|
@ -241,19 +369,23 @@ curl -i https://game.example.com/healthz # 200 ok
|
|||
curl -I https://game.example.com/ # 200, Content-Security-Policy etc.
|
||||
curl -6 -I https://game.example.com/ # over IPv6 (once the AAAA record exists)
|
||||
|
||||
# WebSocket through the proxy (run in /opt/netwall, uses the installed "ws").
|
||||
# (Run here only against the local server, with the URL and origin pointed at it.)
|
||||
# WebSocket through the proxy (run in /opt/netwall, uses the installed "ws"). It creates a room that disappears
|
||||
# again after the 60 s grace period. For a public name on a non-default port use that port in both places.
|
||||
node -e "
|
||||
const WebSocket=require('ws');
|
||||
const ws=new WebSocket('wss://game.example.com/ws',{origin:'https://game.example.com'});
|
||||
ws.on('open',()=>ws.send(JSON.stringify({t:'join',pid:'deploy-check-0001',name:'check'})));
|
||||
ws.on('message',d=>{const m=JSON.parse(d);console.log(m.t,m.room||'');if(m.t==='joined'){ws.close();}});
|
||||
ws.on('message',d=>{const m=JSON.parse(d);if(m.t==='joined'){console.log('joined',m.room);process.exit(0)}});
|
||||
ws.on('unexpected-response',(q,r)=>{console.log('HTTP',r.statusCode);process.exit(1)});
|
||||
ws.on('error',e=>{console.log(e.message);process.exit(1)});
|
||||
setTimeout(()=>{console.log('no reply');process.exit(1)},5000);
|
||||
"
|
||||
# prints: joined XXXX
|
||||
# prints: joined XXXX (or HTTP 403 / 426 / 429 / 502, see section 9)
|
||||
```
|
||||
|
||||
The snippet was run (with the host replaced by a test name and certificate checking off for the self-signed
|
||||
certificate) through nginx with NPM's configuration and printed `joined XXXX`.
|
||||
|
||||
Then open the URL on two phones, create a room on one and enter the 4-letter code on the other.
|
||||
|
||||
## 9. Troubleshooting
|
||||
|
|
@ -261,11 +393,14 @@ Then open the URL on two phones, create a room on one and enter the 4-letter cod
|
|||
| Symptom | Cause and fix |
|
||||
|---|---|
|
||||
| Page loads, but the game says it cannot reach the server / WebSocket never opens | **Websockets Support** is off in the Proxy Host, or something in front strips the `Upgrade` header. Turn it on. |
|
||||
| WebSocket upgrade answered with **403** | Origin check: the browser's `Origin` host differs from the `Host` the server sees. The log says `refused websocket ... Origin "..." does not match Host "..."`. Fix the proxy so `Host` is the public name, or set `ALLOWED_ORIGINS=https://game.example.com` (comma separated for several) and restart. |
|
||||
| Upgrade answered with **429** | More than `MAX_CONN_PER_IP` sockets from one IP. If every visitor appears to come from the proxy, `TRUST_PROXY` is `0`, or the proxy connects from a non-private address; set `TRUST_PROXY=1`. |
|
||||
| WebSocket dies after exactly 60 s | Should not happen with the defaults: the server's 25 s pings keep nginx's 60 s `proxy_read_timeout` fed. If it does, something else sits in the path with its own idle timer (a CDN, a second proxy, a firewall) that is not passing the pings, or the proxy's read timeout is shorter than 25 s. Add the `proxy_read_timeout`/`proxy_send_timeout` snippet (section 5) and check every hop. |
|
||||
| The lobby only says "Could not reach the game server." | That one message covers every failed WebSocket upgrade. The browser's developer-tools console shows the real reason as `Unexpected response code: NNN`; the rows below are by that code. The server log (`journalctl -u netwall -f`) names the reason for 403 and 429. |
|
||||
| WebSocket upgrade answered with **426** | **Websockets Support** is off in the Proxy Host (observed). Turn it on. |
|
||||
| WebSocket upgrade answered with **403** | Origin check: the browser's `Origin` host differs from the `Host` the server sees. The log says `refused websocket from ...: Origin "..." does not match Host "..."`. On a **non-default public port** this is handled automatically for a trusted proxy (section 4, "Origin check"); if the log says `this connection is not from a trusted proxy`, list the proxy in `TRUSTED_PROXIES` (or set `TRUST_PROXY=1`). Otherwise (a proxy that rewrites `Host`, several public names) set `ALLOWED_ORIGINS=https://game.example.com` (comma separated for several, **with `:port` when it is not 80/443**) and restart. |
|
||||
| Upgrade answered with **429** | More than `MAX_CONN_PER_IP` sockets from one address. If the log shows every visitor as the proxy (`from <the proxy's address>`), the proxy is not trusted: it connects from an address the `auto` list does not call private (global IPv6, `100.64.0.0/10`, ...). Set `TRUSTED_PROXIES=<its address>` (section 4, "Client addresses"). If all LAN players share one address in front of nginx, raise `MAX_CONN_PER_IP`. |
|
||||
| Page loads, upgrade answered with **400** `Request Header Or Cookie Too Large` | Big cookies from another application on the same parent domain. Add `large_client_header_buffers 4 16k;` in the Advanced box (section 5), or clear the cookies. |
|
||||
| WebSocket dies after exactly 60 s (or another round number) | Should not happen with the defaults: a joined game receives about 20 snapshots a second, so a proxy idle timer never fires (observed with a 20 s `proxy_read_timeout`). If it does, something else sits in the path that drops connections after a fixed time (a CDN, a second proxy, a firewall, a `proxy_read_timeout` / `proxy_send_timeout` set in the Advanced box that is far lower). Check every hop. |
|
||||
| Players are dropped every few seconds and reconnect | The current client treats a socket as dead after 5 s without data (snapshots arrive 20 times a second). Something is buffering or throttling the stream; look at the proxy's buffering settings and at CPU use of the LXC. |
|
||||
| **502 Bad Gateway** | NPM cannot reach the upstream. `systemctl status netwall`; from the NPM host run `curl -i http://<lxc>:8080/healthz`; check forward IP/port, the firewall (section 6) and that `HOST` is not `127.0.0.1`. |
|
||||
| **502 Bad Gateway** | NPM cannot reach the upstream. (A browser that has loaded the game before still gets the cached app and can play solo while this lasts: observed in Chromium through nginx for 502; 503 and 504 take the same path in the service worker and are covered by a unit test.) `systemctl status netwall`; from the NPM host run `curl -i http://<lxc>:8080/healthz`; check forward IP/port, the firewall (section 6) and that `HOST` is not `127.0.0.1`. |
|
||||
| `listen EADDRINUSE` in the log, service restarts in a loop | Another process uses the port (`ss -ltnp | grep 8080`), or two copies are running. Change `PORT` and the NPM forward port together. |
|
||||
| `IPv6 is not available (...); falling back to 0.0.0.0` | The kernel has no IPv6 at all. IPv4 keeps working; nothing to do, or set `HOST=0.0.0.0` to silence it. With IPv6 merely disabled by sysctl the `::` bind still works. |
|
||||
| IPv6 visitors cannot connect, IPv4 can | The `AAAA` record points somewhere that does not answer on 443, or NPM/the firewall is not listening on IPv6. Test `curl -6 -I https://game.example.com/`. The app itself is dual-stack. |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue