Adds various client launch options (see Troubleshooting.md)
This commit is contained in:
Zef Hemel
2025-08-21 15:22:14 +02:00
parent b7e8d42195
commit 13ee4e4bca
5 changed files with 122 additions and 69 deletions
+31 -5
View File
@@ -42,12 +42,38 @@ safeRun(async () => {
return;
}
}
console.log("Client config", clientConfig);
console.log("Booting SilverBullet client");
if (clientConfig!.readOnly) {
console.log("Running in read-only mode");
// Then we augment the config based on the URL arguments
const urlParams = new URLSearchParams(location.search);
if (urlParams.has("readOnly")) {
clientConfig!.readOnly = true;
}
if (urlParams.has("disableSpaceLua")) {
clientConfig!.disableSpaceLua = true;
}
if (urlParams.has("disableSync")) {
clientConfig!.disableSync = true;
}
if (urlParams.has("disablePlugs")) {
clientConfig!.disablePlugs = true;
}
if (urlParams.has("disableSpaceStyle")) {
clientConfig!.disableSpaceStyle = true;
}
if (urlParams.has("wipeClient")) {
clientConfig!.performWipe = true;
}
if (urlParams.has("resetClient")) {
clientConfig!.performReset = true;
}
// Update the browser URL to no longer contain the query parameters using pushState
if (location.search) {
const newURL = new URL(location.href);
newURL.search = "";
history.pushState({}, "", newURL.toString());
}
console.log("Booting SilverBullet client");
console.log("Client config", clientConfig);
if (navigator.serviceWorker) {
// Register service worker
const workerURL = new URL("service_worker.js", document.baseURI);
+58 -16
View File
@@ -73,6 +73,13 @@ export type ClientConfig = {
spaceFolderPath: string;
indexPage: string;
readOnly: boolean;
// These are all configured via ?query parameters, e.g. ?disableSpaceLua=1
disableSpaceLua?: boolean;
disableSpaceStyle?: boolean;
disablePlugs?: boolean;
disableSync?: boolean;
performWipe?: boolean;
performReset?: boolean;
};
declare global {
@@ -204,6 +211,10 @@ export class Client {
},
);
if (this.clientConfig.disableSync) {
this.syncService.enabled = false;
}
if (!await this.hasInitialSyncCompleted()) {
console.info(
"Initial sync has not yet been completed, disabling page and document indexing to speed this up",
@@ -223,12 +234,23 @@ export class Client {
this.clientSystem.init();
// Check if we need to perform a client wipe
globalThis.onhashchange = () => {
this.checkForWipeClient();
};
if (await this.checkForWipeClient()) {
return;
if (this.clientConfig.performWipe) {
if (confirm("Are you sure you want to wipe the client?")) {
await this.wipeClient();
alert("Wipe done. Please reload the page or navigate away.");
return;
}
}
if (this.clientConfig.performReset) {
if (
confirm(
"Are you sure you want to reset the client? This will wipe all local data and re-sync everything.",
)
) {
await this.wipeClient();
location.reload();
return;
}
}
await this.loadCaches();
@@ -290,16 +312,6 @@ export class Client {
this.updateDocumentListCache().catch(console.error);
}
private async checkForWipeClient(): Promise<boolean> {
if (location.hash === "#--wipe-client") {
console.log("Performing full client wipe");
await this.clientSystem.localSyscall("system.wipeClient", []);
return true;
} else {
return false;
}
}
public hasInitialSyncCompleted(): Promise<boolean> {
return this.syncService.hasInitialSyncCompleted();
}
@@ -1271,6 +1283,10 @@ export class Client {
}
async loadCustomStyles() {
if (this.clientConfig.disableSpaceStyle) {
console.warn("Not loading custom styles, since space style is disabled");
return;
}
if (!await this.hasInitialSyncCompleted()) {
console.info(
"Not loading custom styles yet, since initial synca has not completed yet",
@@ -1579,4 +1595,30 @@ export class Client {
this.focus();
}, 100);
}
async wipeClient() {
if (navigator.serviceWorker) {
// We will attempt to unregister the service worker, best effort
console.log("Getting service worker registrations");
navigator.serviceWorker.getRegistrations().then(
async (registrations) => {
for (const registration of registrations) {
await registration.unregister();
}
console.log("Unregistered all service workers");
},
);
} else {
console.info(
"Service workers not enabled (no HTTPS?), so not unregistering.",
);
}
console.log("Stopping all systems");
this.space.unwatch();
this.syncService.close();
console.log("Clearing data store");
await this.ds.kv.clear();
console.log("Clearing complete.");
}
}
+16
View File
@@ -53,6 +53,7 @@ import {
luaValueToJS,
} from "../lib/space_lua/runtime.ts";
import { buildThreadLocalEnv, handleLuaError } from "./space_lua_api.ts";
import { builtinPlugNames } from "../plugs/builtin_plugs.ts";
const plugNameExtractRegex = /\/(.+)\.plug\.js$/;
const indexVersionKey = ["$indexVersion"];
@@ -208,6 +209,10 @@ export class ClientSystem {
}
async loadScripts() {
if (this.client.clientConfig.disableSpaceLua) {
console.info("Space Lua scripts are disabled, skipping loading scripts");
return;
}
if (!await this.hasFullIndexCompleted()) {
console.info(
"Not loading space scripts, since initial indexing has not completed yet",
@@ -245,6 +250,17 @@ export class ClientSystem {
await Promise.all(allPlugs.map(async (plugMeta) => {
try {
const plugName = plugNameExtractRegex.exec(plugMeta.name)![1];
if (
this.client.clientConfig.disablePlugs &&
!builtinPlugNames.includes(plugName)
) {
console.warn(
"Skipping loading of plug",
plugMeta.name,
"because client config disables plugs",
);
return;
}
await this.system.load(
plugName,
createSandbox(
+1 -23
View File
@@ -101,29 +101,7 @@ export function systemSyscalls(
await client.loadCustomStyles();
},
"system.wipeClient": async (_ctx, logout = false) => {
if (navigator.serviceWorker) {
// We will attempt to unregister the service worker, best effort
console.log("Getting service worker registrations");
navigator.serviceWorker.getRegistrations().then(
async (registrations) => {
for (const registration of registrations) {
await registration.unregister();
}
console.log("Unregistered all service workers");
},
);
} else {
console.info(
"Service workers not enabled (no HTTPS?), so not unregistering.",
);
}
console.log("Stopping all systems");
client.space.unwatch();
client.syncService.close();
console.log("Clearing data store");
await client.ds.kv.clear();
console.log("Clearing complete. All done.");
await client.wipeClient();
if (logout) {
location.href = ".logout";
} else {
+16 -25
View File
@@ -1,6 +1,8 @@
If things don’t work, SilverBullet doesn’t run, a few things to try:
Running into trouble? Sorry to hear it.
If this doesn’t help, ask the [community for help](https://community.silverbullet.md/).
Let’s figure this out.
Here are some things you can try when things don’t work, if you’re still stuck — ask the [community for help](https://community.silverbullet.md/).
# Logs
SilverBullet logs in two places: in your browser and on the server. Most valuable logs are likely going to be in your browser’s logs:
@@ -8,28 +10,17 @@ SilverBullet logs in two places: in your browser and on the server. Most valuabl
* Client logs: Check your browser’s JavaScript console.
* Server logs: Server logs are written to the standard output of the server process. Have a look there too, to see if anything obvious is going on.
# Problems caused by plugs
In case you installed some dysfunctional plug try the following:
# Disable features
Depending on the situation you may (temporarily) disable various client features by appending any of the following to any SilverBullet URL (e.g. `http://localhost:3000/?disableSpaceLua=1`):
* `?disableSync=1` disables synchronization with the server
* `?disableSpaceLua=1` disables loading of all [[Space Lua]] scripts
* `?disableSpaceStyle=1` disables loading of all [[Space Style]]
* `?disablePlugs=1` disables loading of all non built-in [[Plugs]]
* Wipe the `_plug` folder in your space’s folder on the server
* Perform a [[#Full client wipe]] (below)
# Client reset
If all else fails, you may try to perform a full client reset, simply add `?resetClient=1` to any SilverBullet URL.
If you’re now back in a functional state, re-add plugs one by one.
# Full client wipe
In case your client is completely stuck and won’t load anymore, you can perform a full client reset & wipe. This will wipe all local data.
There are two ways to trigger it.
Via your browser’s JavaScript console, run:
```javascript
client.clientSystem.localSyscall("system.wipeClient", []);
```
If you do not have access to your JavaScript console (for instance, because you’re on a phone) you can trigger this by tweaking the URL:
Steps:
1. Append `#--wipe-client` to your SilverBullet URL, e.g. `http://localhost:3000#--wipe-client`.
2. Navigate to the regular URL without `#--wipe-client` after this, and reload your page. This should initiate a full client resync.
This will do the following:
1. Confirm you want to perform a full client reset
2. Wipe all data stored locally in your browser (IndexedDB, unregister the service worker)
3. Reload the client initiating a full resync