@underpostnet/cyberia 3.2.90 → 3.3.73

package/src/server/network/underpost-compression.js

@@ -0,0 +1,186 @@
+/**
+ * Response compression policy for the Nginx workloads on the request path.
+ *
+ * @module src/server/network/underpost-compression.js
+ * @namespace UnderpostCompression
+ */
+
+/**
+ * @constant UNDERPOST_COMPRESSION
+ * @description The compression policy both edge workloads render from.
+ *
+ * `text/html` appears in no type list on purpose: nginx and ngx_brotli both
+ * always compress it, and naming it again only invites the two lists to drift.
+ * Every entry is a format that is still text on the wire — already-compressed
+ * media (png, woff2, mp4) is excluded, since re-encoding it spends CPU to add
+ * bytes.
+ * @memberof UnderpostCompression
+ */
+const UNDERPOST_COMPRESSION = {
+  types: [
+    'application/atom+xml',
+    'application/geo+json',
+    'application/javascript',
+    'application/json',
+    'application/ld+json',
+    'application/manifest+json',
+    'application/rss+xml',
+    'application/vnd.api+json',
+    'application/wasm',
+    'application/x-javascript',
+    'application/xhtml+xml',
+    'application/xml',
+    'font/otf',
+    'font/ttf',
+    'image/svg+xml',
+    'image/x-icon',
+    'text/css',
+    'text/javascript',
+    'text/markdown',
+    'text/plain',
+    'text/xml',
+  ],
+  // Below roughly this size a compressed body plus its headers is no smaller
+  // than the original, and can be larger.
+  minLength: 512,
+  // Level 5 of 9: within a few percent of maximum ratio at a fraction of the
+  // CPU. The edge compresses every response of every host, so the cost of a
+  // higher level is paid on the shared workload, not on one deploy.
+  gzipLevel: 5,
+  // Brotli's scale runs to 11, where dynamic compression becomes slower than
+  // the transfer it saves. 5 is the usual on-the-fly ceiling.
+  brotliLevel: 5,
+  filterModule: 'ngx_http_brotli_filter_module.so',
+  staticModule: 'ngx_http_brotli_static_module.so',
+  defaultImage: 'nginx:alpine',
+  env: {
+    image: 'UNDERPOST_NGINX_IMAGE',
+    brotliModules: 'UNDERPOST_NGINX_BROTLI_MODULES',
+    enabled: 'UNDERPOST_NGINX_COMPRESSION',
+  },
+};
+
+/**
+ * @method nginxImageFactory
+ * @description The image both edge workloads run.
+ *
+ * Resolved in one place because the two have to agree: they sit on the same
+ * request path, and brotli is a property of the image rather than of the
+ * config. An image carrying ngx_brotli is the only way the brotli directives
+ * below can be rendered at all.
+ * @returns {string} Container image reference.
+ * @memberof UnderpostCompression
+ */
+const nginxImageFactory = () =>
+  `${process.env[UNDERPOST_COMPRESSION.env.image] || ''}`.trim() || UNDERPOST_COMPRESSION.defaultImage;
+
+/**
+ * @method brotliModuleDirFactory
+ * @description Directory holding the brotli dynamic modules, or an empty string
+ * when the image is not declared to carry them.
+ *
+ * Empty is the default and the safe state: gzip alone, on a stock image, with
+ * no `load_module` line that could fail to resolve.
+ * @returns {string} Absolute directory path, or `''`.
+ * @memberof UnderpostCompression
+ */
+const brotliModuleDirFactory = () =>
+  `${process.env[UNDERPOST_COMPRESSION.env.brotliModules] || ''}`.trim().replace(/\/+$/, '');
+
+/**
+ * @method compressionEnabledFactory
+ * @description Whether responses are compressed at all.
+ *
+ * The escape hatch for a CPU-bound edge node: compression trades cycles for
+ * bytes, and an operator who is out of the former rather than the latter needs
+ * to turn it off without editing generated configuration.
+ * @returns {boolean} True unless explicitly disabled.
+ * @memberof UnderpostCompression
+ */
+const compressionEnabledFactory = () =>
+  !['off', '0', 'false', 'no'].includes(`${process.env[UNDERPOST_COMPRESSION.env.enabled] || ''}`.trim().toLowerCase());
+
+/**
+ * @method compressionModulesConfFactory
+ * @description The `load_module` lines brotli needs, in nginx's main context.
+ *
+ * Rendered only alongside the brotli directives that require them, so a config
+ * never loads a module it does not use or uses one it did not load — using one
+ * that was not loaded is a start-up failure, and the reverse is surface on a
+ * workload that has no documents to serve from it.
+ * @param {string} [brotliModuleDir] - Directory holding the modules; empty renders nothing.
+ * @param {boolean} [enabled] - Whether compression is on at all.
+ * @param {boolean} [staticRoot] - Whether the workload serves documents from disk.
+ * @returns {string} Main-context directives, or an empty string.
+ * @memberof UnderpostCompression
+ */
+const compressionModulesConfFactory = ({
+  brotliModuleDir = brotliModuleDirFactory(),
+  enabled = compressionEnabledFactory(),
+  staticRoot = false,
+} = {}) => {
+  if (!enabled || !brotliModuleDir) return '';
+  return [
+    `load_module ${brotliModuleDir}/${UNDERPOST_COMPRESSION.filterModule};`,
+    ...(staticRoot ? [`load_module ${brotliModuleDir}/${UNDERPOST_COMPRESSION.staticModule};`] : []),
+  ].join('\n');
+};
+
+/**
+ * @method compressionConfFactory
+ * @description The compression block for an nginx `http` context.
+ *
+ * `gzip_proxied any` is what makes this worth rendering on a reverse proxy at
+ * all: the default is `off`, which suppresses compression for exactly the
+ * responses these workloads exist to forward. A response the upstream already
+ * encoded is passed through untouched either way — nginx never re-compresses
+ * one that carries `Content-Encoding`.
+ *
+ * `*_static` is only rendered where a document root exists. It costs one stat()
+ * per request to serve an operator-placed `.gz`/`.br` sibling with no CPU at
+ * all, and has nothing to look for on a workload that serves no files.
+ * @param {boolean} [enabled] - Whether compression is on at all.
+ * @param {string} [brotliModuleDir] - Directory holding the brotli modules; empty renders gzip alone.
+ * @param {boolean} [staticRoot] - Whether the workload serves documents from disk.
+ * @param {string} [indent] - Leading whitespace for each line.
+ * @returns {string} `http`-context directives, or an empty string.
+ * @memberof UnderpostCompression
+ */
+const compressionConfFactory = ({
+  enabled = compressionEnabledFactory(),
+  brotliModuleDir = brotliModuleDirFactory(),
+  staticRoot = false,
+  indent = '  ',
+} = {}) => {
+  if (!enabled) return '';
+  const types = UNDERPOST_COMPRESSION.types.join(' ');
+  const lines = [
+    'gzip on;',
+    // Compressed and uncompressed bodies share a URL, so a cache that ignores
+    // this header serves one to a client that asked for the other.
+    'gzip_vary on;',
+    `gzip_comp_level ${UNDERPOST_COMPRESSION.gzipLevel};`,
+    `gzip_min_length ${UNDERPOST_COMPRESSION.minLength};`,
+    'gzip_proxied any;',
+    `gzip_types ${types};`,
+    ...(staticRoot ? ['gzip_static on;'] : []),
+  ];
+  if (brotliModuleDir)
+    lines.push(
+      'brotli on;',
+      `brotli_comp_level ${UNDERPOST_COMPRESSION.brotliLevel};`,
+      `brotli_min_length ${UNDERPOST_COMPRESSION.minLength};`,
+      `brotli_types ${types};`,
+      ...(staticRoot ? ['brotli_static on;'] : []),
+    );
+  return lines.map((line) => `${indent}${line}`).join('\n');
+};
+
+export {
+  UNDERPOST_COMPRESSION,
+  brotliModuleDirFactory,
+  compressionConfFactory,
+  compressionEnabledFactory,
+  compressionModulesConfFactory,
+  nginxImageFactory,
+};

package/src/server/{underpost-gateway.js → network/underpost-gateway.js}

@@ -23,18 +23,19 @@
  * `www.cyberiaonline.com` + `/` + 404 becomes
  * `www.cyberiaonline.com/root/status-pages/404/index.html`.
  *
- * @module src/server/underpost-gateway.js
+ * @module src/server/network/underpost-gateway.js
  * @namespace UnderpostGateway
  */
 
 import crypto from 'node:crypto';
 import fs from 'fs-extra';
 import nodePath from 'node:path';
-import { timer } from '../client/components/core/CommonJs.js';
-import { instanceStatusPageEntriesFactory, loadConfServerJson, loadReplicas } from './conf.js';
-import Underpost from '../index.js';
-import { loggerFactory } from './logger.js';
-import { shellExec } from './process.js';
+import { timer } from '../../client/components/core/CommonJs.js';
+import { instanceStatusPageEntriesFactory, loadConfServerJson, loadReplicas } from '../runtime/conf.js';
+import { compressionConfFactory, compressionModulesConfFactory, nginxImageFactory } from './underpost-compression.js';
+import Underpost from '../../index.js';
+import { loggerFactory } from '../ops/logger.js';
+import { shellExec } from '../runtime/process.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -51,7 +52,7 @@ const UNDERPOST_GATEWAY = {
   configMapName: 'underpost-gateway-nginx',
   claimName: 'pvc-underpost-gateway',
   volumeName: 'pv-underpost-gateway',
-  image: 'nginx:alpine',
+  image: nginxImageFactory(),
   root: '/var/www/static',
   port: 80,
   healthPath: '/healthz',
@@ -189,13 +190,24 @@ const defaultStatusPagePath = (status = 404) => `${UNDERPOST_GATEWAY.defaultHost
  * 200. That status is what stops the document being stored: the PWA service
  * worker caches navigations for hours and would otherwise keep serving the
  * fallback long after the host's real page landed in the tree.
+ *
+ * Compression is applied here rather than further out because this is the last
+ * hop that holds a response body in the clear — and, for every host whose
+ * errors are intercepted, the hop every site path already passes through. See
+ * {@link module:src/server/network/underpost-compression.js}.
+ * @param {string} [resolver] - Cluster DNS ClusterIP.
+ * @param {object} [compression] - Overrides for the compression policy.
  * @returns {string} nginx.conf contents.
  * @memberof UnderpostGateway
  */
-const nginxConfFactory = ({ resolver = UNDERPOST_GATEWAY.resolver } = {}) => `worker_processes auto;
+const nginxConfFactory = ({ resolver = UNDERPOST_GATEWAY.resolver, compression = {} } = {}) => {
+  const policy = { ...compression, staticRoot: true };
+  const modules = compressionModulesConfFactory(policy);
+  const compress = compressionConfFactory(policy);
+  return `worker_processes auto;
 error_log /dev/stderr warn;
 pid /tmp/nginx.pid;
-
+${modules ? `${modules}\n` : ''}
 events {
   worker_connections 1024;
 }
@@ -206,12 +218,7 @@ http {
   sendfile on;
   tcp_nopush on;
   server_tokens off;
-
-  gzip on;
-  gzip_vary on;
-  gzip_min_length 512;
-  gzip_types text/html text/css text/plain application/javascript application/json image/svg+xml;
-
+${compress ? `\n${compress}\n` : ''}
   log_format concise '$remote_addr "$request" $status $body_bytes_sent "$host"';
   access_log /dev/stdout concise;
 
@@ -259,6 +266,7 @@ http {
   }
 }
 `;
+};
 
 /**
  * @method statusPageLocationsFactory
@@ -388,6 +396,7 @@ ${blocks
  * @param {string} hostPath - Node directory backing the static root.
  * @param {string} [nodeName] - Node the hostPath volume is pinned to.
  * @param {string} [storage] - Volume size.
+ * @param {object} [compression] - Overrides for the compression policy.
  * @returns {string} Multi-document YAML.
  * @memberof UnderpostGateway
  */
@@ -397,8 +406,9 @@ const underpostGatewayManifestsFactory = ({
   nodeName = '',
   storage = '1Gi',
   resolver,
+  compression = {},
 } = {}) => {
-  const nginxConf = nginxConfFactory({ resolver });
+  const nginxConf = nginxConfFactory({ resolver, compression });
   // The config is mounted with `subPath`, which Kubernetes never refreshes in
   // place, and the pod template is otherwise identical across rebuilds — so
   // without this annotation an edited nginx.conf reaches the ConfigMap and

package/src/server/{underpost-ingress.js → network/underpost-ingress.js}

@@ -20,10 +20,12 @@
  *   holding every host's certificate and re-negotiating ALPN. Passing the bytes
  *   through keeps certificates, HTTP/2 and mTLS exactly where they already work.
  *
- * @module src/server/underpost-ingress.js
+ * @module src/server/network/underpost-ingress.js
  * @namespace UnderpostIngress
  */
 
+import { compressionConfFactory, compressionModulesConfFactory, nginxImageFactory } from './underpost-compression.js';
+
 /**
  * @constant UNDERPOST_INGRESS
  * @description Identity of the underpost ingress workload. One deployment fronts every
@@ -33,7 +35,7 @@
 const UNDERPOST_INGRESS = {
   name: 'underpost-ingress',
   configMapName: 'underpost-ingress-nginx',
-  image: 'nginx:alpine',
+  image: nginxImageFactory(),
   httpPort: 80,
   httpsPort: 443,
   healthPort: 8090,
@@ -100,10 +102,17 @@ const underpostIngressHostMapFactory = ({ contourHosts = [], gatewayHosts = [],
  * that owns most of the routing rather than a rejection, so a host whose route
  * object has not been applied yet still reaches a data plane that can answer it
  * — including with its own 404.
+ *
+ * Compression is rendered for `:80` alone, and that asymmetry is the same split
+ * the module makes everywhere else: an L7 hop holds a body it can encode, while
+ * `:443` carries bytes this process never decrypts. Whatever leaves through the
+ * tunnel on that port was compressed where TLS terminates — see
+ * {@link module:src/server/network/underpost-compression.js}.
  * @param {Array<object>} [entries] - Host table from {@link UnderpostIngress.underpostIngressHostMapFactory}.
  * @param {object} backends - `{contour: {http, tls}, gateway: {http, tls}}`; a missing stack is omitted.
  * @param {string} [defaultBackend] - Backend for an unmatched hostname.
  * @param {string} [resolver] - Cluster DNS ClusterIP.
+ * @param {object} [compression] - Overrides for the compression policy.
  * @returns {string} nginx.conf contents.
  * @memberof UnderpostIngress
  */
@@ -112,6 +121,7 @@ const underpostIngressConfFactory = ({
   backends = {},
   defaultBackend = 'gateway',
   resolver = UNDERPOST_INGRESS.resolver,
+  compression = {},
 } = {}) => {
   const available = Object.keys(backends).filter((name) => backends[name]?.http && backends[name]?.tls);
   // With one stack installed the map still renders, so the same workload serves
@@ -121,17 +131,23 @@ const underpostIngressConfFactory = ({
   const routable = entries.filter((entry) => entry?.host && available.includes(entry.backend));
   const mapEntries = (kind) =>
     routable.map((entry) => `    ${entry.host} ${backends[entry.backend][kind]};`).join('\n') || '';
+  // No `staticRoot`: this workload proxies every byte and serves no documents,
+  // so there is never a pre-compressed sibling on disk to prefer.
+  const policy = { ...compression, staticRoot: false };
+  const modules = compressionModulesConfFactory(policy);
+  const compress = compressionConfFactory(policy);
 
   return `worker_processes auto;
 error_log /dev/stderr warn;
 pid /tmp/nginx.pid;
-
+${modules ? `${modules}\n` : ''}
 events {
   worker_connections 4096;
 }
 
 http {
   server_tokens off;
+${compress ? `\n${compress}\n` : ''}
   log_format underpost_ingress '$remote_addr "$request" $status "$host" -> $underpost_ingress_http_upstream';
   access_log /dev/stdout underpost_ingress;
 

package/src/server/{cri.js → ops/cri.js}

@@ -3,11 +3,11 @@
  * that shells out to `crictl`: the cluster CLI, image management, and the
  * database bootstraps. Lives under `src/server` so the db layer can import it
  * without depending on the CLI god-object.
- * @module src/server/cri.js
+ * @module src/server/ops/cri.js
  * @namespace CriEndpoint
  */
 
-import { shellExec } from './process.js';
+import { shellExec } from '../runtime/process.js';
 
 const CRIO_SOCKET_PATH = '/var/run/crio/crio.sock';