docs/gateway.md: extract big-picture gateway docs, trim in-code comments (mara #775:9988)
mara on PR #775: "this is too much docs in code - move bigger picture stuff to md files and put refs in code" New `docs/gateway.md` consolidates the gateway architecture story that was spreading across long inline comments in `hive-gateway.nix`, `hive-matrix.nix`, and `hive-forge.nix`: - vhost map (which URL serves what, which upstream, which option) - matrix discovery flow (.well-known → sub-domain delegation sequence) - Accept-header SPA fallback pattern (#686 / #729 design history) - local-dev `localHostsEntry` story - sub-domain rationale (mara verdict tracking) + when sub-path is right (hyperhive-internal apps) - per-vhost tuning knobs (forge LFS, matrix long-poll, agent SSE) - sequencing history (which PR added which routing piece) In-code comments in the two nix modules get trimmed to short refs into the doc — keeps the *why* in the markdown while the *what* stays alongside the code: - hive-gateway.nix: top-of-file comment, `agentPortsTable`, `appendHttpConfig`, every location block + vhost - hive-matrix.nix: `fluffychat-web-fixed`, `fluffychat-web-imaging`, the dart compile postInstall README.md gets a new row in the docs table pointing at gateway.md. Verified `nix eval` still resolves the same vhost + location layout after the comment trim — no behavioral change, just less in-code prose.
This commit is contained in:
atlas
mara
parent
df549ed2a5
commit
922057e81b
4 changed files with 171 additions and 314 deletions
|
|
@ -9,50 +9,20 @@ let
|
|||
hyperhiveDomain = config.services.hyperhive.domain;
|
||||
effectiveServerName = if cfg.serverName != null then cfg.serverName else hyperhiveDomain;
|
||||
|
||||
# Three files are missing from nixpkgs's `pkgs.fluffychat-web` dist
|
||||
# because `flutter341.buildFlutterApplication` doesn't run the dart
|
||||
# web-worker compile pass + doesn't run the native_imaging package's
|
||||
# emscripten build (#685):
|
||||
#
|
||||
# - native_executor.js ← flutter web worker entry, compiled
|
||||
# from web/native_executor.dart via
|
||||
# `dart compile js` (handled inline
|
||||
# in `fluffychat-web-fixed.postInstall`
|
||||
# below — dart SDK is already in the
|
||||
# flutter341 closure)
|
||||
#
|
||||
# - Imaging.js / Imaging.wasm ← emscripten-compiled C library from
|
||||
# the native_imaging dart package
|
||||
# (vendored by Famedly). The package
|
||||
# ships C source + a Makefile that
|
||||
# builds them via emcc; nixpkgs's
|
||||
# flutter builder doesn't run that
|
||||
# pipeline. Built from source via
|
||||
# `fluffychat-web-imaging` below
|
||||
# (per mara's #685 call: "fix the
|
||||
# compile … dont use the prebuilt
|
||||
# binary").
|
||||
#
|
||||
# When `flutter341.buildFlutterApplication` grows worker + emcc
|
||||
# support upstream, drop both this derivation and the postInstall.
|
||||
# Three files are missing from `pkgs.fluffychat-web` because
|
||||
# `flutter341.buildFlutterApplication` doesn't run the dart
|
||||
# web-worker compile pass + doesn't run the native_imaging emscripten
|
||||
# build (#685). `fluffychat-web-imaging` below builds the latter from
|
||||
# source via `pkgs.emscripten`; the worker compile is inline in
|
||||
# `fluffychat-web-fixed.postInstall`. Drop both when nixpkgs's
|
||||
# flutter builder grows worker + emcc support upstream.
|
||||
|
||||
# Imaging.{js,wasm} built from source: native_imaging's `js/Makefile`
|
||||
# runs `emcmake cmake` → `make -C build` → `emcc` to produce the
|
||||
# emscripten-wrapped C library that fluffychat's main.dart.js
|
||||
# references at runtime.
|
||||
#
|
||||
# Source: the exact native_imaging derivation that `pkgs.fluffychat-web`
|
||||
# already pulls in via its `pubspecLock` (resolved by nixpkgs's flutter
|
||||
# pub-cache machinery), reached via `passthru.pubspecLock.dependencySources`.
|
||||
# This means **no parallel hash pin** — when nixpkgs bumps
|
||||
# `pkgs.fluffychat-web` (and with it the pubspec.lock-resolved
|
||||
# native_imaging version), our build automatically picks up the
|
||||
# matching source. Version is also pulled from passthru for the
|
||||
# derivation's `version` attr so it stays in lockstep.
|
||||
#
|
||||
# Closure cost: `pkgs.emscripten` is ~3.6 GiB build-time (LLVM +
|
||||
# toolchain). Runtime closure is only the two produced files —
|
||||
# nothing emscripten-shaped survives into the deployed dist.
|
||||
# `Imaging.{js,wasm}` built from `native_imaging`'s C source via
|
||||
# emscripten. Source comes from
|
||||
# `pkgs.fluffychat-web.passthru.pubspecLock.dependencySources` so
|
||||
# there's no parallel hash pin — version auto-syncs with nixpkgs
|
||||
# bumps. Build closure +~3.6 GiB (emscripten LLVM); runtime closure
|
||||
# is just the two output files.
|
||||
fluffychat-web-imaging = pkgs.stdenv.mkDerivation {
|
||||
pname = "fluffychat-web-imaging";
|
||||
version = pkgs.fluffychat-web.passthru.pubspecLock.dependencyVersions.native_imaging;
|
||||
|
|
@ -102,14 +72,9 @@ let
|
|||
};
|
||||
};
|
||||
|
||||
# `pkgs.fluffychat-web` with #685's three missing files patched
|
||||
# in via postInstall. No `--base-href` override anymore (#772 moves
|
||||
# fluffychat from the bare-domain `<hive>/matrix/` sub-path to the
|
||||
# `matrix.<hive>/` sub-domain root; upstream's default `--base-href
|
||||
# "/"` is correct at sub-domain root). The previous `/matrix/`
|
||||
# override from #634 + #754 (forge sub-domain pattern) lived here
|
||||
# until the matrix sub-domain vhost in #764 made the sub-path
|
||||
# redundant.
|
||||
# `pkgs.fluffychat-web` with #685's three missing files patched in
|
||||
# via postInstall. Mount point is `matrix.<hive>/` (#772); upstream
|
||||
# `--base-href "/"` is correct at sub-domain root, no override.
|
||||
fluffychat-web-fixed = pkgs.fluffychat-web.overrideAttrs (old: {
|
||||
# `dart` from the flutter341 closure (already pulled, no
|
||||
# incremental closure cost) so we can compile the web-worker
|
||||
|
|
@ -119,34 +84,14 @@ let
|
|||
postInstall =
|
||||
(old.postInstall or "")
|
||||
+ ''
|
||||
# #685: compile web/native_executor.dart → native_executor.js.
|
||||
# The flutter web bootstrap loads this from /matrix/native_executor.js
|
||||
# at startup; without it, main.dart.js logs a network-error and
|
||||
# the SPA renders blank (see #643 for the symptom).
|
||||
#
|
||||
# `dart compile js` needs `.dart_tool/package_config.json` to
|
||||
# resolve `package:matrix/...` and the rest of fluffychat's
|
||||
# `pubspec.lock` deps. buildFlutterApplication's pub-get step
|
||||
# writes that file to the build CWD (the unpacked source dir),
|
||||
# not to `$src` (the read-only nix store path). So we must use
|
||||
# a relative path that walks up from `web/` to the build CWD
|
||||
# where pub-get's package_config lives — pointing at
|
||||
# `$src/web/native_executor.dart` walks up to `$src/`, finds
|
||||
# no `.dart_tool/`, and fails with `Couldn't resolve the
|
||||
# package 'matrix'` (mara's first build attempt on #685).
|
||||
#
|
||||
# nixpkgs's buildFlutterApplication leaves CWD at the source
|
||||
# root for postInstall (see `pkgs/development/compilers/flutter/
|
||||
# build-support/build-flutter-application.nix` — installPhase
|
||||
# is `cp -r build/web "$out"` with no `cd` first). So `web/...`
|
||||
# resolves correctly here.
|
||||
# `web/...` is relative to build CWD so dart's package_config
|
||||
# walk-up hits buildFlutterApplication's pub-get output (#685
|
||||
# / #733 fixup — `$src/web/...` would walk up to a read-only
|
||||
# store path with no `.dart_tool/`).
|
||||
${pkgs.flutter341.dart}/bin/dart compile js \
|
||||
-o $out/native_executor.js \
|
||||
web/native_executor.dart
|
||||
|
||||
# #685: install Imaging.{js,wasm} built from the native_imaging
|
||||
# dart package's C source via emscripten (see
|
||||
# `fluffychat-web-imaging` above for the build-time rationale).
|
||||
install -m 644 ${fluffychat-web-imaging}/Imaging.js $out/Imaging.js
|
||||
install -m 644 ${fluffychat-web-imaging}/Imaging.wasm $out/Imaging.wasm
|
||||
'';
|
||||
|
|
|
|||
Loading…
Reference in a new issue