Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions capsules/browser/browser/browser-status.js
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@ export function friendlyOpenError(error) {
: "This browser cannot show the Browser session. Use a supported browser or enable WebRTC.";
}
if (outcome?.state === "terminal_pre_effect_failure" && error?.payload?.stage === "engine_readiness") {
if (error?.payload?.code === "browser_host_setup_required") {
return sanitizedErrorText({ message: error.payload.message || text });
}
switch (error?.payload?.reason) {
case "artifact_invalid":
return "Browser Engine files need repair. Prepare this Engine or choose another approved Engine.";
Expand Down
14 changes: 14 additions & 0 deletions capsules/browser/browser/browser-status.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,20 @@ test("readiness failures explain the repair while cleanup retains priority", ()
}
});

test("Linux host setup guidance names the opt-in command", () => {
const error = openError("terminal_pre_effect_failure");
Object.assign(error.payload, {
stage: "engine_readiness",
code: "browser_host_setup_required",
message: "Browser is available on this computer. To turn it on, run: elastos setup --browser. Then close Home and start it again with elastos home --browser.",
});
assert.equal(friendlyOpenError(error), error.payload.message);
error.payload.message = "Browser needs KVM on this computer. After KVM is available, run: elastos setup --browser. Then close Home and start it again with elastos home --browser.";
assert.equal(friendlyOpenError(error), error.payload.message);
error.payload.outcome.state = "cleanup_pending";
assert.doesNotMatch(friendlyOpenError(error), /elastos setup --browser/);
});

test("one-page capacity refusal says only one Browser window can be open", () => {
for (const state of ["terminal_pre_effect_failure", "terminal_post_effect_cleanup"]) {
const error = openError(state);
Expand Down
25 changes: 18 additions & 7 deletions docs/BROWSER_VM_TARGET.md
Original file line number Diff line number Diff line change
Expand Up @@ -483,22 +483,32 @@ guest and viewer allocations meet; loopback, private ranges and every other
peer are denied, and TCP relays are off. coturn checks peer IPs only, so the
relay output rule above confines relayed UDP to the TURN ports; host services
on the slot IP stay unreachable. `check` refuses a receipt without that rule.
`elastos setup` writes the Home's TURN credential to the
`elastos setup --browser` writes the Linux Home's TURN credential to the
owner-only `$DATA_DIR/runtime-turn/turn-credentials.env` and keeps an
existing one.

For removal, use the same root shell and helper:
The Linux installer leaves Browser host access and its image to the Home owner.
On a supported Linux ARM64 host with KVM, run `elastos setup --browser` from a
terminal. This command admits the signed helpers, runs the one-time administrator
setup above, checks host access, then downloads and verifies the image with
progress. The administrator helper shows its changes and asks for confirmation.
Ordinary `elastos setup` leaves the Linux Browser image untouched. Close Home
and start it again after enabling Browser. Browser open explains this command
on an unprepared host; after setup it prepares a missing image on demand.
Apple Silicon setup keeps its existing Browser preparation behavior.

For removal, close Browser and run this as the Home user before uninstalling:

```sh
python3 /usr/local/lib/elastos/browser-vm-linux-network.py remove --user <home-user>
sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)"
```

After confirmation, removal deletes this account's TAPs, filter hooks/chains,
boot service, udev rule, locks and receipts. It restores the prior named KVM
ACL, or removes the grant created by setup. The shared root helper is removed
when the last account's setup is removed. Other host firewall rules stay with
their owner. `install.sh` integration is a separate change; the installer can
call the exact setup command above as its approved root step.
their owner. Runtime and the installer leave these administrator operations
to the explicit Browser setup and removal commands.

### Linux operator proof

Expand Down Expand Up @@ -562,8 +572,9 @@ generator/stager for:
- verified links to an existing rootfs, kernel, initrd and matching build manifest

Linux uses the native supervisor and a disposable qcow2 overlay for each
launch. The installer removes the retired `browser-vm/rootfs-pool` image copies
as their ordinary owner and reports the removed path.
launch. Linux Browser preparation belongs to `elastos setup --browser`.
That command removes retired `browser-vm/rootfs-pool` image copies as their
ordinary owner before preparing Browser.

For already-provisioned targets, `scripts/browser-vm-target-refresh.sh` is the
host-helper maintenance path. Guest drift requires a rebuilt image set. Runtime
Expand Down
43 changes: 26 additions & 17 deletions docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,9 @@ stop after bootstrap.

The current default Home exposes Assistant, Chat (Community), System, People,
Wallet, Documents, Library, Marketplace, and Inbox. On Apple Silicon
Macs it also exposes Browser; Linux Homes do not show Browser in 2.0.0. People is installed as a
Macs it also exposes Browser. On supported Linux ARM64 computers with KVM,
Browser is optional; see [Jetson](#jetson) for `elastos setup --browser`.
People is installed as a
separate app capsule; Home presents it but does not own its state or authority.

Native Windows is not an accepted install target today. The current product
Expand Down Expand Up @@ -173,20 +175,27 @@ The installer detects Linux `aarch64`:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bash
```

Home and chat use the ordinary user account. Browser runs on Apple Silicon Macs
and uses the local Engine's virtual machine. When the signed release supplies
Browser support, setup obtains its matching helpers and verified image before
Home starts. The image streams to disk with progress; a transfer stops after 30
seconds without data. Runtime keeps the committed Browser profile separate from
the image during reopen and updates.

On other computers, including Linux ARM64 (Jetson) and Linux x86-64, Browser is
hidden until the next release; setup prints "Browser is not available on this
computer yet." Setup also clears the Browser Engine selection and removes the
Browser host helpers and image an earlier release installed (Browser profiles
stay). The installer runs its Linux host step only after setup and only if the
helper is still present, so it asks for no administrator step. If an earlier
release set up Browser host access on Linux, it can be removed with:
Home and chat use the ordinary user account. Browser uses the local Engine's
virtual machine on Apple Silicon Macs and supported Linux ARM64 hosts with KVM.
On Linux, Marketplace lists Browser with its setup command. To turn it on, run
`elastos setup --browser` in a terminal as the user who installed Home. The
command installs the signed Browser helpers, shows the host access changes and
asks for administrator approval. It then downloads and verifies the image with
progress. Close Home and start it again with `elastos home --browser`.

The Linux installer and ordinary `elastos setup` leave Browser preparation to
your choice until you enable it. Home lists Browser on supported Linux ARM64
computers; opening it before setup explains the command and restart. After you
enable Browser, ordinary setup refreshes its signed helpers and image during
updates. A later open repairs missing or changed helpers and prepares a missing
image on demand. Apple Silicon setup continues to prepare its helpers and image
before Home starts. The image
streams to disk with progress; a transfer stops after 30 seconds without data.
Runtime keeps the committed Browser profile separate from the image during
reopen and updates. Linux x86-64 keeps Browser hidden and retires helpers and
images from unsupported releases while preserving Browser profiles.

To remove Browser host access, close Browser and run this before uninstalling:

```sh
sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)"
Expand Down Expand Up @@ -502,8 +511,8 @@ directory stays, including Browser profiles, so installing again continues with
the same identity. Pass the same `--install-dir` you installed with. An install
or update that is running or was interrupted stops the removal; finish it first.

On Linux, the uninstall leaves any Browser host access an earlier release set
up in place. Remove it with:
On Linux, the administrator helper owns Browser host access. If you enabled it,
close Browser and remove that access before uninstalling:

```sh
sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)"
Expand Down
1 change: 1 addition & 0 deletions elastos/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ release's Added, Changed, Fixed, Removed and Security bullets before you update;
### Fixed

- On a Jetson, Browser uses more of the processor, so scrolling is about twice as smooth.
- On Linux, Browser is turned on when you choose it, not during install.
- Open apps, including Chat, stay connected while Home runs, and reconnect by themselves after a network drop or a restart.
- The installer uses numeric process age to verify and stop a running Home with any time locale (#517).
- The installer repairs group-writable files in an older Home that you own and gives one ownership repair command for root-owned installation files (#516).
Expand Down
6 changes: 3 additions & 3 deletions elastos/crates/elastos-server/src/api/browser_capsules.rs
Original file line number Diff line number Diff line change
Expand Up @@ -430,7 +430,7 @@ fn list_launchable_browser_capsules_for(
if !capsule_is_offered(data_dir, &manifest.name) {
continue;
}
if manifest.name == "browser" && !crate::setup::home_browser_available(data_dir, platform) {
if manifest.name == "browser" && !crate::setup::browser_available(platform) {
continue;
}
let Ok(capsule) = resolve_browser_capsule(data_dir, &manifest.name) else {
Expand Down Expand Up @@ -1494,12 +1494,12 @@ mod tests {
}

#[test]
fn browser_is_launchable_only_on_hosts_with_a_local_engine() {
fn browser_is_launchable_on_supported_hosts_before_setup() {
let data_dir = tempfile::tempdir().unwrap();
write_test_browser_capsule(data_dir.path(), "browser", "Browser", "app");
for (platform, listed) in [
("linux-amd64", false),
("linux-arm64", false),
("linux-arm64", true),
("darwin-arm64", true),
] {
let names: Vec<_> = list_launchable_browser_capsules_for(data_dir.path(), platform)
Expand Down
71 changes: 64 additions & 7 deletions elastos/crates/elastos-server/src/api/gateway_browser.rs
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ pub(super) struct BrowserProviderResourceCall {
}

#[derive(Debug)]
struct BrowserOpenFailure {
pub(in crate::api::gateway) struct BrowserOpenFailure {
status: StatusCode,
body: BrowserOpenFailureBody,
outcome: serde_json::Value,
Expand Down Expand Up @@ -194,7 +194,7 @@ impl BrowserOpenFailure {
(status, Json(self.status_value())).into_response()
}

fn status_value(&self) -> serde_json::Value {
pub(in crate::api::gateway) fn status_value(&self) -> serde_json::Value {
let mut value = match &self.body {
BrowserOpenFailureBody::Text(message) => serde_json::json!({
"schema": "elastos.browser.open-error/v1",
Expand Down Expand Up @@ -459,6 +459,7 @@ pub(super) async fn browser_app_open(
input,
home_token,
request_origin,
&crate::setup::detect_platform(),
)
.await
{
Expand All @@ -485,6 +486,7 @@ pub(super) async fn browser_app_open(
input,
home_token,
request_origin,
&crate::setup::detect_platform(),
)
.await
{
Expand Down Expand Up @@ -561,13 +563,34 @@ fn browser_open_status_value(open_id: &str, snapshot: BrowserOpenJobSnapshot) ->
}
}

async fn execute_browser_open(
fn browser_host_setup_failure(
data: &std::path::Path,
platform: &str,
adapter_id: Option<&str>,
) -> Option<BrowserOpenFailure> {
if adapter_id.is_some_and(|id| id != "browser-vm-product") {
return None;
}
crate::setup::linux_host_setup_message(data, platform).map(|message| {
BrowserOpenFailure::json(
StatusCode::CONFLICT,
serde_json::json!({
"code": "browser_host_setup_required",
"stage": "engine_readiness",
"message": message,
}),
)
})
}

pub(in crate::api::gateway) async fn execute_browser_open(
state: &GatewayState,
context: HomeLaunchTokenContext,
authority: RuntimeWalletAuthority,
input: BrowserOpenRequest,
home_token: Option<String>,
request_origin: Option<String>,
platform: &str,
) -> Result<serde_json::Value, BrowserOpenFailure> {
let BrowserOpenRequest {
url: requested_url,
Expand Down Expand Up @@ -595,6 +618,23 @@ async fn execute_browser_open(
err.to_string(),
));
}
let requested_adapter_id = match browser_engine_adapter_id(adapter_id) {
Ok(value) => value,
Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)),
};
if requested_adapter_id
.as_deref()
.is_none_or(|id| id == "browser-vm-product")
{
crate::setup::repair_browser_host_components_for_open(&state.data_dir, platform)
.await
.map_err(|error| BrowserOpenFailure::provider("browser-engine", error))?;
}
if let Some(failure) =
browser_host_setup_failure(&state.data_dir, platform, requested_adapter_id.as_deref())
{
return Err(failure);
}
let registry = match state.provider_registry.as_ref().cloned() {
Some(registry) => registry,
None => {
Expand All @@ -614,10 +654,6 @@ async fn execute_browser_open(
Ok(value) => value,
Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)),
};
let requested_adapter_id = match browser_engine_adapter_id(adapter_id) {
Ok(value) => value,
Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)),
};
let browser_instance = match browser_instance_id(browser_instance) {
Ok(value) => value,
Err(message) => return Err(BrowserOpenFailure::text(StatusCode::BAD_REQUEST, message)),
Expand Down Expand Up @@ -4627,6 +4663,27 @@ fn browser_display_error_response(error: BrowserDisplayError) -> Response {
mod browser_open_outcome_tests {
use super::*;

#[test]
fn unprepared_linux_browser_open_explains_setup_and_restart_before_acquiring_effects() {
let data = tempfile::tempdir().unwrap();
for adapter in [None, Some("browser-vm-product")] {
let failure = browser_host_setup_failure(data.path(), "linux-arm64", adapter).unwrap();
assert_eq!(failure.status, StatusCode::CONFLICT);
let body = failure.status_value();
assert_eq!(body["code"], "browser_host_setup_required");
assert_eq!(body["stage"], "engine_readiness");
let message = body["message"].as_str().unwrap();
assert!(message.contains("elastos setup --browser"));
assert!(message.contains("close Home and start it again with elastos home --browser"));
assert_eq!(body["outcome"]["effects"]["vm_acquired"], false);
}
assert!(
browser_host_setup_failure(data.path(), "linux-arm64", Some("remote-engine")).is_none()
);
assert!(browser_host_setup_failure(data.path(), "darwin-arm64", None).is_none());
assert!(std::fs::read_dir(data.path()).unwrap().next().is_none());
}

#[test]
fn failed_open_serializes_cleanup_pending_separately_from_pre_effect_failure() {
let pending = BrowserOpenFailure::text(
Expand Down
Loading
Loading