mirror of
https://github.com/Such-Software/adaptive-multi-protocol-browser.git
synced 2026-10-17 22:41:25 +02:00
Harden browser docs and transport recovery
This commit is contained in:
jwinterm
+5
-1
@@ -1,6 +1,6 @@
|
||||
# Autodocs
|
||||
|
||||
> Status: draft | Updated 2026-07-07 | Applies to: AMPB maintainers
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB maintainers
|
||||
|
||||
Public docs should stay concise and current. Code-owned behavior is documented from code,
|
||||
while manual docs explain stable concepts and operator-facing choices.
|
||||
@@ -41,3 +41,7 @@ Run:
|
||||
```sh
|
||||
python3 tools/docs_check.py
|
||||
```
|
||||
|
||||
The public docs gate checks status headers, internal links, repo-contained local links,
|
||||
private fixture target names, obvious private-key blocks, common API tokens, and assigned
|
||||
secret values. Private notes belong under ignored `docs/private/`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Browser Builds
|
||||
|
||||
> Status: draft | Updated 2026-07-07 | Applies to: AMPB desktop and mobile builders
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB desktop and mobile builders
|
||||
|
||||
AMPB browser builds must keep source checkouts, object directories, toolchain caches, and
|
||||
temporary artifacts outside this repository. The default local workspace is
|
||||
@@ -99,8 +99,9 @@ system `tor` binary if one is present.
|
||||
Managed I2P startup currently targets `i2pd`. AMPB adopts an existing HTTP proxy on
|
||||
`127.0.0.1:4444` when available; otherwise `ampbrowser open <i2p-url> --yes --launch`
|
||||
uses `AMPB_I2PD_BIN`, configured `transports.i2p.binary_path`, or a system `i2pd` binary.
|
||||
The AMPB-owned process writes config, router data, logs, and ownership metadata under
|
||||
`.ampb/transports/i2p`.
|
||||
If no provider is found, AMPB returns a structured setup hint and install command for the
|
||||
CLI and route-helper page. The AMPB-owned process writes config, router data, logs, and
|
||||
ownership metadata under `.ampb/transports/i2p`.
|
||||
|
||||
## Source Plan
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Desktop Vertical
|
||||
|
||||
> Status: draft | Updated 2026-07-07 | Applies to: AMPB desktop builders
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB desktop builders
|
||||
|
||||
The first AMPB browser proof is desktop-first with mobile constraints kept in view. The
|
||||
vertical is a bundled Gecko desktop runtime, AMPB-owned profile state, and a managed Tor
|
||||
@@ -26,10 +26,10 @@ artifacts are available for the selected checkout.
|
||||
|
||||
## Transport Path
|
||||
|
||||
The first transport target is Tor through an AMPB-owned Arti/Tor runtime. The desktop
|
||||
vertical is not complete until AMPB can start the runtime, verify the SOCKS endpoint, and
|
||||
launch the bundled browser profile without clearnet fallback. I2P and Reticulum use the
|
||||
same route, consent, state, and health-check model after Tor works.
|
||||
The first transport target is Tor through an AMPB-owned Arti/Tor runtime. The current
|
||||
desktop vertical can launch a bundled Gecko runtime, start a route-aware helper, and keep
|
||||
the helper tied to the browser process. I2P uses the same route, consent, state, and
|
||||
health-check model. Reticulum follows after the resilient-network adapter is concrete.
|
||||
|
||||
## Desktop Shell
|
||||
|
||||
|
||||
+8
-7
@@ -1,6 +1,6 @@
|
||||
# Open Flow
|
||||
|
||||
> Status: draft | Updated 2026-07-08 | Applies to: AMPB users and implementers
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB users and implementers
|
||||
|
||||
`ampbrowser open` prepares a safe launch plan for one URL. It routes the URL, checks only
|
||||
the selected transport, and reports whether the browser can open immediately or needs a
|
||||
@@ -34,12 +34,13 @@ adopted daemon from an AMPB-owned managed process.
|
||||
through a desktop dialog when possible, falls back to a terminal prompt when needed, and
|
||||
launches through the same transport runner after approval.
|
||||
|
||||
`ampbrowser open <url> --route-aware --launch` creates one desktop profile for clearnet,
|
||||
Tor, and I2P. The profile uses a PAC file for `.onion` and `.i2p` routing, installs the
|
||||
AMPB route-helper extension, and starts a token-gated loopback helper tied to the browser
|
||||
process. If a user clicks an alternate-network link before its local transport is ready,
|
||||
the extension shows a setup page and asks the helper to start the AMPB-managed transport
|
||||
after approval.
|
||||
`ampbrowser open <url> --route-aware --launch` creates a desktop convenience profile for
|
||||
clearnet, Tor, and I2P QA. The profile uses a PAC file for `.onion` and `.i2p` routing,
|
||||
installs the AMPB route-helper extension, and starts a token-gated loopback helper tied
|
||||
to the browser process. If a user clicks an alternate-network link before its local
|
||||
transport is ready, the extension shows a setup page and asks the helper to start the
|
||||
AMPB-managed transport after approval. This mode proves routing and first-use setup; it
|
||||
is not the final per-transport storage isolation model.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Test Fixtures
|
||||
|
||||
> Status: draft | Updated 2026-07-05 | Applies to: AMPB and AMPG compatibility testing
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB and AMPG compatibility testing
|
||||
|
||||
Fixtures should cover static sites, protocol-specific publishing, and interactive web
|
||||
apps without exposing private deployment notes.
|
||||
@@ -13,9 +13,8 @@ HTML improvements that improve alternate renderers.
|
||||
|
||||
## Interactive Fixtures
|
||||
|
||||
`ai-gen-bot` and `medusa-multi-tenant-platform` are stretch fixtures for dynamic behavior:
|
||||
sessions, forms, asset policy, script policy, tenant routing, and transport-specific
|
||||
degradation.
|
||||
Stretch fixtures cover dynamic behavior: sessions, forms, asset policy, script policy,
|
||||
tenant routing, payments, job-style workflows, and transport-specific degradation.
|
||||
|
||||
## Fixture Requirements
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Transport Management
|
||||
|
||||
> Status: draft | Updated 2026-07-08 | Applies to: AMPB transport adapters
|
||||
> Status: draft | Updated 2026-07-11 | Applies to: AMPB transport adapters
|
||||
|
||||
Transport management follows one rule: use what is already healthy, and manage missing
|
||||
transports only after the user opens a URL that needs them and approves setup.
|
||||
@@ -13,9 +13,14 @@ With `--launch --yes`, AMPB can start configured Tor and I2P providers with AMPB
|
||||
state before launching. Transport policy comes from `.ampb/config.toml` or an explicit
|
||||
`--config` path.
|
||||
|
||||
`ampbrowser transport start|status|stop <name>` exposes the same ownership model without
|
||||
launching a browser. It records only AMPB-owned processes and refuses to stop adopted
|
||||
user or system daemons.
|
||||
`ampbrowser transport start|status|stop|repair <name>` exposes the same ownership model
|
||||
without launching a browser. It records only AMPB-owned processes and refuses to stop
|
||||
adopted user or system daemons.
|
||||
|
||||
Transport results include `setup_hint` and `install_command` when AMPB knows how the
|
||||
user can install a missing provider. I2P currently reports Homebrew, apt, dnf, pacman,
|
||||
or pkg guidance where applicable, plus the `AMPB_I2PD_BIN` and
|
||||
`transports.i2p.binary_path` override path.
|
||||
|
||||
Route-aware desktop launches add a local helper process for in-browser setup prompts. The
|
||||
helper accepts token-gated loopback requests from the AMPB profile extension, reports
|
||||
@@ -43,12 +48,24 @@ Managed transports store runtime state under `.ampb/transports/<name>` by defaul
|
||||
leases, tunnels, and daemon logs in that tree are local state and must not be committed.
|
||||
AMPB records owned process metadata in `.ampb/transports/<name>/ampb-owned.json`.
|
||||
|
||||
If a managed transport reports ready but a route is flaky because of stale cache, bad
|
||||
guard selection, or corrupt local daemon state, reset only that transport with:
|
||||
|
||||
```sh
|
||||
python3 -m ampbrowser transport repair tor
|
||||
python3 -m ampbrowser transport start tor
|
||||
```
|
||||
|
||||
`repair` stops an AMPB-owned process when one is recorded, removes
|
||||
`.ampb/transports/<name>`, and leaves `.ampb/profiles/<name>` untouched. It refuses to
|
||||
erase runtime state if AMPB cannot stop a recorded live owned process.
|
||||
|
||||
## Current Adapters
|
||||
|
||||
- Tor: detect SOCKS on `127.0.0.1:9050`; managed start supports Arti, configured `tor`,
|
||||
and system `tor` providers with AMPB-owned state.
|
||||
- I2P: detect HTTP proxy on `127.0.0.1:4444`; managed start supports configured or system
|
||||
`i2pd` providers with AMPB-owned state.
|
||||
- I2P: detect HTTP proxy on `127.0.0.1:4444`; managed start supports configured, bundled,
|
||||
Homebrew, or system `i2pd` providers with AMPB-owned state.
|
||||
- IPFS: detect HTTP gateway on `127.0.0.1:8080`; managed gateway start planned.
|
||||
- Gemini: built-in route and render path; no daemon required for static browsing.
|
||||
- Reticulum: resilient/private route contract exists; adapter and readiness model are planned.
|
||||
|
||||
Reference in New Issue
Block a user