dat-thang/docs/dillo.md

Dillo integration

Use the Dillo source maintained at https://git.dillo-browser.org/dillo. The project also lists https://codeberg.org/dillo/dillo as an up-to-date mirror; that mirror was used for the Linux run documented below. The latest published release is 3.2.0; the current source tree identifies its development version as 3.3.0. The old dillo.org host is not controlled by the Dillo developers.

make builds $(BUILD)/dat.dpi (normally build/linux/dat.dpi), a native C Dillo Plugin Interface (DPI) helper. It uses Dillo's external DPIP protocol and does not link against Dillo internals or depend on a particular browser ABI. The helper authenticates each accepted DPIP connection with the ~/.dillo/dpid_comm_keys value and handles open_url and DpiBye. It follows the historical plugin lifecycle: dpid passes its listening socket on stdin, the helper accepts a request connection, and closes that connection after the response body. DPIP responses do not use HTTP status lines or Content-Length; closing the request socket marks the end of the page. Current Dillo continues to load .dpi plugins and associate them with protocols in ~/.dillo/dpidrc.

Build and install the DPI with the same prefix used by Dillo. For the usual /usr/local installation:

make
sudo make install

If Dillo uses a different plugin directory, set PREFIX and DPIDIR on both commands. The default plugin path is /usr/local/lib/dillo/dpi/dat/dat.dpi. The per-user ~/.dillo/dpidrc must contain both the DPI root and this mapping (Dillo does not merge dpi_dir from the system config into the per-user file):

dpi_dir=/usr/local/lib/dillo/dpi
proto.dat=dat/dat.dpi

Then restart Dillo (which restarts dpid). The plugin first checks Dillo's local archive cache. On a cache miss it can join the archive's Cesspool topic, authenticate a peer session, fetch the metadata and content feeds, and then serve the requested path. Both Dillo's DPI and the seeding Dat-thang client must use the same Cesspool bootstrap node. Configure that endpoint for the environment that launches each program:

build/linux/dat bootstrap set 127.0.0.1:3282

The command stores the node in ~/.config/dat-gpt/bootstrap. For a public test, use the reachable HOST:PORT of the Cesspool node instead of the local loopback address. The Cygwin Dillo and native Windows Dat-thang configurations are separate when their HOME directories differ, so configure each using its own dat executable/environment. The helper does not use Hyperswarm or Hypercore; its remote feed transfer uses this project's Cesspool and SLEEP session protocol.

Use the full key shown by Dat-thang, then enter dat://<key>/ in Dillo. The helper caches fetched data at ~/.dillo/dat/archives/XX/<remaining-key> and serves historical versions, index.html, .html fallback, explicit // directory listings, parent-directory navigation, stat queries, and the MIME rules used by the old dillo-dat plugin. Directory listings retain its up/directory/file icons and sort directories first, then names in descending order. The internal dpi:/dat/ page lists archives opened by this DPI process, shows title, description, and version from dat.scm (read as an S-expression without evaluating archive contents), falls back to CNAME, and provides the unswarm/reload and quit controls. Status messages identify name resolution, archive retrieval, and file serving. If a fetch cannot complete, it returns a text error page that distinguishes an unconfigured or unreachable node, no peer announcing the archive key, and a peer transfer timeout.

Version pins use the metadata-entry count shown by dat status: dat://<key>+2/ reads the snapshot at version 2, while dat://<key>/ follows the latest version. Root navigation looks for index.html. make test checks the archive behaviors and starts the helper with a real TCP listening socket, then verifies response bytes and EOF framing over an accepted connection.

Linux bootstrap, Dat-thang, and Dillo smoke run

Run these steps from the repository root after installing the build dependencies in INSTALL. GNU/Linux objects and executables default to build/linux, separate from the Windows build in build/windows. The bundled site/ archive already has an address and three recorded versions; this flow leaves it unchanged.

Build and install the GUI plus the C Dillo helper:

./configure
make ENABLE_SDL2=1
sudo make ENABLE_SDL2=1 install

Merge these entries into ~/.dillo/dpidrc, preserving any other DPI entries, then restart Dillo so dpid reloads the mapping:

dpi_dir=/usr/local/lib/dillo/dpi
proto.dat=dat/dat.dpi

Use three terminals. Terminal 1 runs a local discovery node for this same-host smoke run. Start it before either client so it receives the initial announce:

build/linux/cesspool-bootstrap --bind 127.0.0.1 --port 3282 \
  --state-dir "$HOME/.local/state/dat-gpt/cesspool-bootstrap" \
  --advertise 127.0.0.1:3282

Terminal 2 configures the client and starts the SDL client with the bundled archive explicitly loaded. Leave its window open and online:

build/linux/dat bootstrap set 127.0.0.1:3282
DDAT_BOOTSTRAP=127.0.0.1:3282 DDAT_PORT=3000 \
  build/linux/dat-thang --archive "$PWD/site"

Terminal 3 starts Dillo with an empty per-run cache, so the page must arrive from the archive being announced by Dat-thang. The temporary home gives Dillo its own fresh cache and DPID keys without disturbing the normal profile: keep this shell open for the two dilloc version checks below.

dillo_home=$(mktemp -d)
mkdir -p "$dillo_home/.dillo"
cat > "$dillo_home/.dillo/dpidrc" <<'EOF'
dpi_dir=/usr/local/lib/dillo/dpi
proto.dat=dat/dat.dpi
EOF
archive=$(build/linux/dat url / "$PWD/site")
HOME="$dillo_home" DDAT_BOOTSTRAP=127.0.0.1:3282 dillo "$archive/" &
sleep 5
HOME="$dillo_home" dilloc title
HOME="$dillo_home" dilloc dump | grep -F 'The site is online'

The latest site/ snapshot is version 3 and displays “Site is online.” Open the version-1 pin in the existing Dillo window to verify historical navigation; it predates dat.scm and index.html and shows the earlier archive listing:

historical=$(build/linux/dat url 1 / "$PWD/site")
HOME="$dillo_home" dilloc open "$historical/"
sleep 2
HOME="$dillo_home" dilloc url
HOME="$dillo_home" dilloc dump | grep -F 'dat-logo.png'

Return to the setup page at version 3:

latest=$(build/linux/dat url 3 / "$PWD/site")
HOME="$dillo_home" dilloc open "$latest/"
sleep 2
HOME="$dillo_home" dilloc url
HOME="$dillo_home" dilloc title
HOME="$dillo_home" dilloc dump | grep -F 'The site is online'

For another archive, replace site with its loaded local archive directory, and choose a version from build/linux/dat log DIRECTORY. The same Cesspool node must be reachable by both the Dat-thang GUI and Dillo helper. The bootstrap process reports announced peer and topic counts. A successful run shows the GUI online, a cold Dillo cache populated with .dat/metadata.remote and .dat/content.remote, and the Dillo title Site is online. With this archive, Dillo loads both +1 (historical listing) and +3 (the current setup page).

Windows with Cygwin Dillo

Build the helper from the repository root in Cygwin Bash. The DPI uses the normal Cygwin gcc, make, libcurl-devel, and libsodium-devel packages. The helper links the bundled S7 reader so dat.scm metadata is parsed using the project's Scheme representation; it never evaluates archive-supplied forms.

make build/linux/dat.dpi
install -d /usr/local/lib/dillo/dpi/dat
install -m 755 build/linux/dat.dpi /usr/local/lib/dillo/dpi/dat/dat.dpi.exe

Put both entries in ~/.dillo/dpidrc (for this installation that is C:\cygwin64\home\Home\.dillo\dpidrc):

dpi_dir=/usr/local/lib/dillo/dpi
proto.dat=dat/dat.dpi.exe

Restart Dillo so dpid reads the configuration. The site/ folder in this repository is the archive source; Dillo's cache is separate at ~/.dillo/dat/archives/XX/<remaining-key>. A seeded archive is browseable only after its feed data is present in that cache or a live Cesspool fetch completes. The setup page source is site/index.html. tests/test_dpi.sh checks the historical and latest snapshots, S-expression metadata, listing, stat, and dashboard output. The Windows end-to-end flow, including +N navigation across multiple archives, has been confirmed by the user. The Linux cold-cache flow above was also run against current Dillo source and the Cesspool bootstrap.