snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Holesail Service Daemon + Bin Client

Browse Source
This commit is contained in:
Raven Scott
2026-04-09 20:42:54 -04:00
parent 3a69906046
commit c8c877f688
168 changed files with 387155 additions and 30713 deletions
Download Patch File Download Diff File Expand all files Collapse all files
handbook/04-the-booter-runtime.md
+15
View File
@@ -220,6 +220,21 @@ Disable the unit for the next boot with **`~/.config/bare-os/initd/disabled.txt`
---
## bare-holesail (Holesail P2P proxy)
**`bare-holesail.js`** wires the upstream **`holesail`** package (**AGPL-3.0**) using **only** its public class API (no direct Hyperswarm / HyperDHT usage in this integration). Under **`pear run`**, the booter cannot bare-**`import('holesail')`** from **`pear:`** modules, so **`bare-holesail`** resolves the class from **`ctx.bare.holesail`** when the drive merge succeeded, else **`import.meta.resolve('holesail')`**, else a one-off eval of **`/lib/bare/bundles/holesail.js`** via **`ctx.vfs`** (same IIFE semantics as **`maybeMergeBareFromDrive`**).
- **Initd unit `bare-holesail`** — **On by default** ( **`BARE_OS_HOLESAIL_INITD=1`** and **`BARE_OS_HOLESAIL_MANAGED=1`** in stock **`shellEnv`** unless the host sets them empty or to **`0`/`false`**). Disable for a session with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** ( **`~/.config/bare-os/initd/disabled.txt`**). Either **managed multi-tunnel** or **single env tunnel**:
- **Managed (persisted list)** — Stock default (**`BARE_OS_HOLESAIL_MANAGED=1`**). Tunnel definitions live in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, under the session **`$HOME`** on the personal drive). On unit start, every **enabled** entry gets its own **`holesail`** instance. Use guest **`/bin/holesail`** ( **`ctx.bareOsRunHolesailCli`**) to **`list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`enable`**, **`disable`**, **`restart`**.
- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, **`BARE_OS_HOLESAIL_KEY=…`** when in client mode, and optional **`BARE_OS_HOLESAIL_SECURE`**, **`BARE_OS_HOLESAIL_PORT`**, **`BARE_OS_HOLESAIL_HOST`**, **`BARE_OS_HOLESAIL_UDP`**, **`BARE_OS_HOLESAIL_LOG`**.
Starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
- **Early booter (“kernel-path”) instance** — Separate optional instance started **after** the **`repl`** boot phase and **before** **`startBareInitd`**. Enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror of the options above (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Uses **`registerKernelShutdownHook`** for teardown. **`hs.pause()` / `hs.resume()`** run on mobile suspend/resume hooks alongside other subsystems.
- **Guest scripts** — Use **`ctx.bare.holesail`** (bundled under **`/lib/bare/bundles/holesail.js`**), not **`require('holesail')`**, because **`/bin`** and **`/boot/init.js`** are not Node modules. **`/bin/holesail`** is the operator CLI for persisted tunnels (see managed mode above). See **`kernel/etc/bare-os/kernel.d/.README`**.
Set **`BARE_OS_HOLESAIL_DEBUG=1`** for extra console lines (URLs only; keys are not logged in full).
---
## Shell session, controlling TTY sketch, and job-control gaps
The interactive shell keeps **`ctx.shellSessionState`**: **`sid`** (session id), **`nextPgid`** (for **`&` background jobs**), **`foregroundPgid`** (set to a job’s **`pgid`** while **`fg`** awaits that job, otherwise reset toward **`sid`** after each foreground line), and **`controllingTty`** (**`/dev/console`** or **`ipc:<session-fifo>`** when **`BARE_OS_SESSION_FIFO`** / **`BARE_OS_IPC_SESSION_FIFO`** is set). Background jobs record **`sid`** / **`pgid`** in **`ctx.shellBackgroundJobs`** for **`jobs`** output. **Cooperative logical job control:** **`suspend-job`** sets **`stopped`** and the background runner yields between statements until **`fg`** or **`bg`** clears it; there is still no **`tcsetpgrp`** and no host **`SIGTSTP`/`SIGCONT`**. Host **SIGINT** may arrive as **`bare-os:host-sigint`** (via optional **`bare-signals`** or **`process.on('SIGINT')`**) for cooperative cancellation; **`ctx.bareOsSendSignal`** also records **PIPE** / **CHLD** / **USR1** / **USR2** on synthetic PIDs without ending the session.