CDN Web Host module

This module serves a versioned Web Host asset graph from the application deployment. The Web Host build exporter supplies files under assets/ and writes assets/asset-manifest.json. The manifest lists each asset path, MIME type, byte size, SHA-256 digest, and exact placeholder count.

Configuration

Set wippy.cdn.web_host:public_url to the public application origin and optional external path prefix, such as https://example.test/tenant. The value must use HTTP or HTTPS with a DNS host or valid IPv4 address, and it must not contain credentials, a query, or a fragment. IPv6 literals are not supported. Prefix segments accept letters, digits, underscores, tildes, dots, and hyphens after percent decoding. The module appends the versioned route /cdn/web-host/webcomponents-1.0.67.

When the URL is empty or invalid, the Facade contributor leaves its configured Host selection unchanged. Assets that need URL replacement return 503 with Cache-Control: no-store until a valid URL is configured. Other manifest-listed files remain available.

The contributor supplies fe_facade_url and host_policy_mode=shared when the module URL is valid. An explicit application resolver value for fe_facade_url suppresses both contributed values. An explicit resolver value for host_policy_mode is retained. The module reads its own public_url requirement; it does not read CDN settings from Facade contributor inputs.

The module requires Facade >=0.6.46 <0.7.0 so its config and CSS handlers can invoke the existing application resolver. An explicit resolver value for fe_facade_url still takes precedence.

Configure the module where the application declares its dependencies:

- name: cdn_web_host
  kind: ns.dependency
  component: wippy/cdn-web-host
  version: "0.0.67"
  parameters:
    - name: server
      value: app:gateway
    - name: public_url
      value: https://my-app.example/tenant

Use the application's HTTP service entry for server. Facade discovers the module's wippy.facade.config_contributor function and receives fe_facade_url=https://my-app.example/tenant/cdn/web-host/webcomponents-1.0.67. It uses that value for the Host entrypoint and passes the normal AppConfig to the Host. Facade has no dependency on the CDN module, and no separate Facade Host URL setting is required.

Check the application's Facade config response at /api/public/facade/config and the browser Network panel after loading the app. The endpoint is /facade/config below the router bound to Facade; /api/public is the default router prefix. Host assets should load below that versioned URL. A path prefix relocates the Host assets; it does not relocate Facade's own root-relative bootstrap routes.

Serving and cache behavior

The router serves /cdn/web-host/webcomponents-1.0.67/{path} using only paths listed in the embedded manifest. It supports GET and HEAD. Unknown paths return 404. Invalid paths return 400 before an asset file is read.

Unchanged assets use the source manifest digest as their ETag and receive immutable caching. Text assets with placeholder replacements receive the configured deployment URL, no ETag, and Cache-Control: no-store. The module accepts manifests up to 8 MiB with at most 10,000 files, and each asset can be up to 64 MiB. The module does not provide acquisition, administration, a database, or CDN Core integration.

Version pairing

The Host exporter substitutes 1.0.67 and 0.0.67 from the root package version when preparing the installable module. The manifest must use schema version 1, identify the matching Host and module versions, and contain the exact versioned route prefix. The manifest file is not listed in its own files array.

Build and release from the Host source

The Host repository owns the module source and release scripts. Its module Makefile and Windows wrappers are in wippy/cdn-web-host/ and are excluded from the exported module. The exported module directory is generated output and needs no Host submodule. Module builds and publication are manual; Host CI does not publish Wippy modules.

Use Node.js 22 or later and pnpm 10.24.0. Check out the matching Host release tag over SSH:

git clone --branch webcomponents-1.0.67 --single-branch git@git.spiralscout.com:estimation-engine/wippy-web-host.git web-host-1.0.67
cd web-host-1.0.67
corepack enable
corepack prepare pnpm@10.24.0 --activate
pnpm install --frozen-lockfile
make -C wippy/cdn-web-host build

On Windows, run .\wippy\cdn-web-host\make.bat build from the Host repo root. The tag must contain the module Makefile, release script, and module scaffold. Tags before the first release of this module do not support this workflow.

The build validates the selected tag, source commit, version pair, and exported hashes. It writes artifacts/wippy-cdn-web-host/ below the Host repo root without publishing. Set WIPPY_CLI to an absolute native Wippy CLI path and run make -C wippy/cdn-web-host check to validate native packaging with publish --dry-run. Run make -C wippy/cdn-web-host publish-prepared to publish the prepared module, or make -C wippy/cdn-web-host release to build, validate, and publish in one command. Windows uses the same targets through wippy/cdn-web-host/make.bat.

Publication uses the native CLI's existing credentials and requires publishing permission. For the first publication, add CREATE=1 to publish-prepared or release (on Windows, set $env:CREATE = '1' first) to create the public Hub module named CDN Web Host. Later releases omit it. It packs and publishes the validated source directory; it does not retain a WAPP for a separate archive upload. Credentials stay outside the Host repository and its CI. The build-draft and check-draft targets support local work before tagging, but publication commands reject draft provenance.