IslandAssets

IslandAssets — serves the island client runtime and compiled WASM bundles.

Reads compiled WASM files and a Forge-generated manifest from disk. The manifest (priv/static/islands/manifest.json) maps island module names to content-hash filenames, enabling long-lived immutable caching:

{
  "MyApp.Islands.Counter":   { "file": "counter-a1b2c3d4.wasm",   "hash": "a1b2c3d4" },
  "MyApp.Islands.SearchBar": { "file": "search_bar-e5f6g7h8.wasm", "hash": "e5f6g7h8" }
}

URL routes (under the configured base_path, default "/_bastion"):

/_bastion/islands.js              — bundled island client runtime
/_bastion/islands-ws.js           — WebSocket connection script
/_bastion/islands/manifest.json   — WASM manifest (served with short cache)
/_bastion/islands/{file}.wasm     — compiled island WASM (immutable if hashed)

Usage (as a plug):

HttpServer.new(4000)
|> HttpServer.plug(IslandAssets.plug(IslandAssets.default_config()))
|> HttpServer.plug(Router.to_plug(router))
|> HttpServer.listen()

Or serve specific assets from a controller:

fn js_handler(conn : Conn) : Conn do
  IslandAssets.serve_js(conn)
end

Types

typeAssetConfigAssetConfig = AssetConfig(String)#

Functions

fnconfig_base_pathconfig_base_path(cfg : AssetConfig) : String#

Return the base path from a config.

fndefault_configdefault_config() : AssetConfig#

Create a default config that serves assets under /_bastion.

fnmake_configmake_config(base_path : String) : AssetConfig#

Create a config with a custom base path.

fnplugplug(cfg : AssetConfig) : Conn -> Conn#

Build a Conn -> Conn plug that serves island asset files.

Routes handled (relative to base_path):
  /islands.js            — main island client runtime (JS + WASM bridge)
  /islands-ws.js         — WebSocket connection script
  /islands/manifest.json — WASM manifest (module name → hashed filename)
  /islands/{file}.wasm   — compiled island WASM bundle

Non-matching requests pass through unchanged.

fnserve_jsserve_js(conn : Conn) : Conn#

Serve the main island client runtime JS.

Concatenates idiomorph.js + march-islands.js + wasm-bridge.js from
priv/js/ and serves them as a single response.

fnserve_manifestserve_manifest(conn : Conn) : Conn#

Serve the WASM island manifest (priv/static/islands/manifest.json).

The manifest maps island module names to hashed WASM filenames.  It is
intentionally served with a short cache (60 s) so clients pick up new
deploys quickly, while individual .wasm files get immutable caching.
Returns 200 with an empty JSON object if the manifest file is not found.

fnserve_wasm_fileserve_wasm_file(conn : Conn, filename : String) : Conn#

Serve a compiled island WASM file by its filename (e.g. "counter-a1b2c3d4.wasm").

Looks up the file under priv/static/islands/{filename}, falling back to
islands/{filename}.  Files with an 8-char content hash (e.g. name-a1b2c3d4.wasm)
are served with immutable Cache-Control; unhashed files get a short cache.
Returns 404 if the WASM file is not present.

fnserve_ws_jsserve_ws_js(conn : Conn) : Conn#

Serve the WebSocket connection JS.

fnwasm_cache_controlwasm_cache_control(filename : String) : String#

fnwasm_urlwasm_url(base : String, module_name : String) : Option(String)#

Look up the hashed filename for an island module in the manifest, and return its full URL path under the given base.

Returns None if the manifest is absent or the island is not listed.

Example:
  IslandAssets.wasm_url("/_bastion", "MyApp.Islands.Counter")
  -- Some("/_bastion/islands/counter-a1b2c3d4.wasm")