@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.6

package/cordis.patch.yml

@@ -0,0 +1,94 @@
+# This file is the bundle patch declared by package.json's `dsh.bundle.patch`.
+# It mounts the plugin explicitly at `./tools` rather than relying on a
+# "root export is the plugin" convention, so reading this file tells you which
+# module of the package becomes the plugin.
+#
+# ---------------------------------------------------------------------------
+# Why this is an `insert:` list and not a bare `- id: w2m`
+# ---------------------------------------------------------------------------
+# A bare `- id: w2m` entry is a *non-insert* patch: it replaces fields on an
+# entry that an earlier layer already created. No earlier layer creates `w2m`,
+# so the Loader reports
+#
+#   dsh: [@twinsearth/w2m-dsh-plugin] patch: entry "w2m" not found
+#
+# and skips it. Measured with DSH 0.2.0-rc.2 (`--dump-config-schema`, $defs.patch):
+#
+#   "An insert appends entries, optionally inside the group identified by id.
+#    Other patches replace supplied fields; ... Unknown targets and non-insert
+#    patches without a nonempty id are warned and skipped."
+#
+# The consequence of the old shape was silent: `dsh plugin add` succeeded, the
+# profile listed the bundle, DSH started cleanly -- and **no `w2m` row was ever
+# composed**, so none of the eight tools existed. `--dump-config` showed 183 rows
+# and zero of them named this package.
+#
+# ---------------------------------------------------------------------------
+# Configuring the relay URL, and the direct path (v0.4.0)
+# ---------------------------------------------------------------------------
+# The relay URL has a default as of v0.4.0: the shared W2M server, which hosts the
+# relay, a STUN server and a reverse proxy on one address. Leaving `rabbitUrl` empty
+# therefore means "use the shared server", not "guess" -- and `w2m_status` reports
+# `rabbit_source: "shared-default"` with a note naming the address, so a machine
+# talking to somebody else's host can never be a surprise.
+#
+# The order is `rabbitUrl` -> `W2M_RABBIT_URL` -> the shared server, and an explicit
+# value always wins. Set one of the first two to run against your own relay:
+#
+#   - id: w2m
+#     config:
+#       rabbitUrl: https://w2m.example.com        # may include a sub-path
+#       operatorToken: !!js process.env.W2M_OPERATOR_TOKEN
+#       stateDir: !!js (process.env.DSH_HOME + '/xclient')
+#
+# `operatorToken` is the credential that authorises *sending* instructions. It is
+# separate from the per-machine device token on purpose: a machine that can receive
+# work should not automatically be able to command the others. The relay writes it to
+# <state>/operator-token.txt on first start and prints it once.
+#
+# `p2pMode` decides how a dispatched offer travels, and it is the release's headline
+# switch, so every value is validated at load and a typo is refused rather than
+# defaulted:
+#
+#   auto    (default) punch the direct path and push the offer over it; the relay's
+#           own offer on the SSE stream stays as the fallback, so a failed punch is
+#           invisible to the caller except in `direct_pushes` and each machine's
+#           `transport`. This is what `W2M_P2P_MODE` unset gives you.
+#   direct  the same push, but a failed punch is not hidden: the executor refuses an
+#           offer that did not arrive over the direct path
+#           (`refusal_reason: P2P_UNAVAILABLE`), so a fleet that must use the fast
+#           path fails loudly instead of quietly falling back.
+#   relay   no UDP socket is bound at all and nothing is dialled -- exactly v0.3.9's
+#           behaviour. Use it to take the direct path out of the picture entirely
+#           while diagnosing something else.
+#
+#   - id: w2m
+#     config:
+#       p2pMode: relay                            # or W2M_P2P_MODE=relay
+#
+# `stunServers` is the list used to discover the address a peer can reach this machine
+# on. Unset means the shared server first, then three public fallbacks -- the shared
+# server is asked first on purpose, because a machine that can reach the relay can
+# reach that STUN server, so the address it reports is measured over the same path the
+# punch will use. Naming servers replaces that list, so give the shared one explicitly
+# if you still want the relay's own path measured:
+#
+#   - id: w2m
+#     config:
+#       stunServers: ['202.182.123.154:3478', 'stun.example.com:3478']
+#                                                # or W2M_STUN_SERVERS=a:3478,b:3478
+#
+# A loopback punch (both machines on one host) exercises the code path and says nothing
+# about NAT traversal; `w2m_status` reports the measured NAT mapping so the difference
+# is visible rather than assumed.
+- insert:
+    - id: w2m
+      name: '@twinsearth/w2m-dsh-plugin/tools'
+      config:
+        rabbitUrl: ''
+        operatorToken: ''
+        autoStartAgent: false
+        machineName: ''
+        allowedCommands: []
+        p2pMode: auto
+        stunServers: []

package/deploy/caddy/Caddyfile.example

@@ -0,0 +1,118 @@
+# ============================================================================
+#  W2M relay behind Caddy  --  example configuration
+# ============================================================================
+#
+#  This file is a TEMPLATE. Replace every <placeholder> before using it.
+#
+#  Validated how: caddy is not installed on the authoring machine, so this file
+#  was NOT checked with `caddy validate`. Run that on the server before
+#  reloading -- docs/DEPLOY.md gives the exact commands.
+#
+#  ---------------------------------------------------------------------------
+#  WHY CADDY NEEDS ONE EXPLICIT SETTING FOR SSE
+#  ---------------------------------------------------------------------------
+#  Caddy 2 enables automatic HTTPS (issuance + renewal) with no extra
+#  configuration, which is its main advantage over nginx here. It also buffers
+#  responses by default, like nginx -- but unlike nginx it does NOT honour the
+#  relay's `X-Accel-Buffering: no` header, because that header is an
+#  nginx-specific convention.
+#
+#  So the setting that matters is:
+#
+#      flush_interval -1
+#
+#  Without it the browser connects to /v1/stream, receives no events, and the
+#  UI looks "connected but dead" -- the same failure `proxy_buffering off`
+#  prevents under nginx.
+#
+#  Caddy handles HTTP/1.1 and HTTP/2 correctly by itself, so the other two
+#  nginx-side SSE requirements have no Caddy equivalent.
+#
+#  ---------------------------------------------------------------------------
+#  SHAPE 1: served at the root of a dedicated hostname (recommended).
+#  Replace <your-domain> with a name whose A/AAAA record points at this server.
+#  Relay flags: no --base-path, no --tls-cert/--tls-key (Caddy terminates TLS).
+# ============================================================================
+
+<your-domain> {
+	# ---- the event stream: this route alone needs flush_interval ----------
+	@stream path /v1/stream
+	handle @stream {
+		reverse_proxy 127.0.0.1:8787 {
+			# Disable response buffering: frames must reach the client as
+			# they are written. This is the Caddy equivalent of nginx's
+			# `proxy_buffering off`, and it is the single most important
+			# line in this file.
+			flush_interval -1
+
+			# The stream is long-lived and quiet between the relay's 15s
+			# keepalive comments, so let it stay open indefinitely.
+			transport http {
+				read_timeout 0
+				write_timeout 0
+			}
+		}
+	}
+
+	# ---- health check, unauthenticated on purpose -------------------------
+	handle /healthz {
+		reverse_proxy 127.0.0.1:8787
+	}
+
+	# ---- everything else --------------------------------------------------
+	handle {
+		reverse_proxy 127.0.0.1:8787 {
+			flush_interval -1
+		}
+	}
+
+	# ---- logging ----------------------------------------------------------
+	# Off by default in Caddy. Turn it on while bringing a deployment up: it is
+	# the fastest way to see whether a client reached /v1/stream, and whether
+	# Caddy itself (not the relay) answered 401/403/404.
+	log {
+		output file /var/log/caddy/w2m-access.log {
+			roll_size 10MiB
+			roll_keep 5
+		}
+		format json
+	}
+}
+
+# ============================================================================
+#  SHAPE 2: served under a sub-path, e.g. https://<your-domain>/w2m/
+# ============================================================================
+#  Uncomment and adapt when the relay must share a hostname with something else.
+#
+#  Start the relay with `--base-path /w2m` and forward the prefix UNCHANGED.
+#  Caddy's `handle_path` strips the prefix -- using it here is the classic
+#  mistake and produces 404 on every /v1/* call. `handle` preserves the path.
+#
+#  Client `rabbitUrl` must carry the same prefix:
+#      https://<your-domain>/w2m
+# ============================================================================
+
+# <your-domain> {
+# 	@stream path /w2m/v1/stream
+# 	handle @stream {
+# 		reverse_proxy 127.0.0.1:8787 {
+# 			flush_interval -1
+# 			transport http {
+# 				read_timeout 0
+# 				write_timeout 0
+# 			}
+# 		}
+# 	}
+#
+# 	# The relay answers /healthz both with and without the prefix, so a probe
+# 	# on either path keeps working; this keeps the bare one reachable.
+# 	handle /healthz {
+# 		reverse_proxy 127.0.0.1:8787
+# 	}
+#
+# 	handle /w2m/* {
+# 		reverse_proxy 127.0.0.1:8787 {
+# 			flush_interval -1
+# 		}
+# 	}
+# }

package/deploy/docker/Dockerfile

@@ -0,0 +1,144 @@
+# ============================================================================
+#  W2M relay (Rabbit) — multi-architecture container image
+# ============================================================================
+#
+#  Build from the repository root (the COPY paths are relative to the context):
+#
+#      docker build -f deploy/docker/Dockerfile -t w2m-relay:0.3.4 .
+#
+#  Multi-arch, without needing the target hardware:
+#
+#      docker buildx build --platform linux/amd64,linux/arm64 \
+#          -f deploy/docker/Dockerfile -t w2m-relay:0.3.4 .
+#
+#  ---------------------------------------------------------------------------
+#  ZERO RUNTIME DEPENDENCIES — this is the reason the image is so small
+#  ---------------------------------------------------------------------------
+#  The relay declares `"dependencies": {}` and genuinely has none. Its complete
+#  import closure is 7 files / ~175 KiB and resolves to exactly seven node:
+#  builtins:
+#
+#      bin/w2m-rabbit.mjs -> src/relay/server.mjs, src/util/cli.mjs
+#      src/relay/server.mjs -> state.mjs, persistence.mjs, report.mjs, ../signing.mjs
+#      src/relay/{state,report,persistence}.mjs -> state.mjs
+#      builtins: node:crypto node:fs node:http node:https node:os node:path node:util
+#
+#  Therefore **no package manager runs in this image** — there is no `npm
+#  install`, no `npm ci`, no lockfile to go stale and no registry access at
+#  build time. If a future change needs an npm package, that would break a core
+#  project promise and should be raised, not added here.
+#
+#  `lib/` is deliberately absent: it is the DSH *plugin* entry
+#  (`package.json` "main": "lib/index.js") and the relay CLI never imports it.
+#  `cordis.patch.yml` is likewise plugin-host configuration, not relay runtime.
+#
+#  ---------------------------------------------------------------------------
+#  PINNING
+#  ---------------------------------------------------------------------------
+#  The base tag is pinned to an exact patch release, not `22` or `latest`: a
+#  floating tag makes two builds of the same commit produce different images.
+#
+#  `node:22.23.3-bookworm-slim` is the current 22.x LTS line (v22.23.3 released
+#  2026-09-23, verified against https://nodejs.org/dist/index.json). The *tag's
+#  existence in the registry* could not be checked from the authoring machine —
+#  see deploy/docker/README.md, "What was verified".
+#
+#  For byte-for-byte reproducibility, pin the digest instead. Resolve it with:
+#      docker buildx imagetools inspect node:22.23.3-bookworm-slim
+#  and replace the FROM line with `node:22.23.3-bookworm-slim@sha256:<digest>`.
+#  Note a digest names ONE platform, so a multi-arch build needs the per-arch
+#  digests from the manifest list.
+# ============================================================================
+
+FROM node:22.23.3-bookworm-slim
+
+# Fixed uid/gid so a bind-mounted state directory has predictable ownership on
+# the host (a random uid would make `ls -l` on the host meaningless).
+ARG W2M_UID=10001
+ARG W2M_GID=10001
+
+# `production` keeps any transitive tooling quiet and is honest about intent:
+# nothing in this image is a dev dependency.
+ENV NODE_ENV=production
+
+# ---------------------------------------------------------------------------
+# Runtime payload — exactly the import closure above, nothing else.
+# ---------------------------------------------------------------------------
+WORKDIR /app
+
+# `--chown` takes the numeric uid/gid, which is portable (BuildKit and the
+# classic builder both accept it) and avoids a separate `RUN chown -R /app`
+# layer that would duplicate every file's bytes.
+COPY --chown=10001:10001 bin/w2m-rabbit.mjs /app/bin/w2m-rabbit.mjs
+COPY --chown=10001:10001 src/relay/ /app/src/relay/
+COPY --chown=10001:10001 src/util/ /app/src/util/
+COPY --chown=10001:10001 src/signing.mjs /app/src/signing.mjs
+
+# ---------------------------------------------------------------------------
+# Unprivileged user
+# ---------------------------------------------------------------------------
+# The uid/gid above are pinned by ARG, so keep the numbers in the COPY lines
+# equal to the defaults here. (Docker cannot interpolate an ARG inside --chown,
+# so if you change W2M_UID/W2M_GID you must change these four lines too.)
+RUN groupadd --gid "${W2M_GID}" w2m \
+ && useradd --uid "${W2M_UID}" --gid "${W2M_GID}" --no-create-home --shell /usr/sbin/nologin w2m \
+ && mkdir -p /var/lib/w2m \
+ && chown "${W2M_UID}:${W2M_GID}" /var/lib/w2m
+
+USER w2m
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+# devices.json (device tokens), ledger.jsonl (task ledger) and
+# operator-token.txt (0600) live here. Losing this volume means every paired
+# machine must pair again, so it is a VOLUME rather than image content.
+#
+# /var/lib/w2m is also the relay's $HOME, which is where it falls back to
+# `$HOME/.dsh/xclient/rabbit` when `--state` is not given — so the volume covers
+# the default and the explicit path alike.
+ENV HOME=/var/lib/w2m
+VOLUME ["/var/lib/w2m"]
+
+EXPOSE 8787
+
+# ---------------------------------------------------------------------------
+# Health check
+# ---------------------------------------------------------------------------
+# GET /healthz needs NO credential, which is exactly why it is the right probe
+# here: the container must be able to report itself healthy without holding the
+# operator token (that token authorises SENDING work and must not leak into
+# image configuration).
+#
+# `node -e` is used instead of curl/wget so the image needs no extra packages —
+# keeping the "install nothing" property intact through the health check too.
+#
+# The probe is deliberately hard-coded to 8787. The container's listen port is
+# fixed at 8787 and the *host* port is what varies (see docker-compose.yml), so
+# this probe never needs to change. If you override the command's --port, you
+# must override this HEALTHCHECK to match.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+    CMD ["node", "-e", "fetch('http://127.0.0.1:8787/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+
+# ---------------------------------------------------------------------------
+# How it starts
+# ---------------------------------------------------------------------------
+# `--host 0.0.0.0` is correct HERE and only here. Inside a container the loopback
+# interface is unreachable from outside its network namespace, so a loopback
+# bind would make the published port useless. Exposure is controlled by the port
+# *mapping* instead — docker-compose.yml binds 127.0.0.1 on the host by default,
+# so nothing is published to the outside world until the operator says so.
+#
+# TLS terminates in front of this container (nginx/Caddy on the host, or a
+# tunnel), which is why the default invocation carries no --tls-cert/--tls-key:
+# the relay behind a proxy speaks plain HTTP over a loopback-only VPS hop.
+# `--trust-proxy` is NOT in the default command on purpose — turn it on only
+# when a proxy you control really is in front, because with it on the relay
+# believes X-Forwarded-For and a directly-reachable client could forge its
+# address past the pairing rate limit.
+#
+# Add flags per deployment shape, e.g. behind nginx/Caddy:
+#   docker run ... w2m-relay:0.3.4 --host 0.0.0.0 --port 8787 \
+#       --state /var/lib/w2m --trust-proxy
+ENTRYPOINT ["node", "/app/bin/w2m-rabbit.mjs"]
+CMD ["--host", "0.0.0.0", "--port", "8787", "--state", "/var/lib/w2m"]