@powersync/diagnostics 0.0.1 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -5
- package/lib/src/agent-server.d.ts +21 -0
- package/lib/src/agent-server.js +51 -0
- package/lib/src/agent-server.js.map +1 -0
- package/lib/src/agent.d.ts +10 -29
- package/lib/src/agent.js +10 -57
- package/lib/src/agent.js.map +1 -1
- package/lib/src/client.js +5 -4
- package/lib/src/client.js.map +1 -1
- package/lib/src/definition.d.ts +7 -1
- package/lib/src/definition.js +15 -0
- package/lib/src/definition.js.map +1 -1
- package/lib/src/index.d.ts +2 -2
- package/lib/src/index.js +1 -1
- package/lib/src/index.js.map +1 -1
- package/lib/src/js-agent.d.ts +5 -13
- package/lib/src/js-agent.js +14 -12
- package/lib/src/js-agent.js.map +1 -1
- package/lib/src/node.d.ts +4 -3
- package/lib/src/node.js +5 -3
- package/lib/src/node.js.map +1 -1
- package/lib/src/page.js +2 -3
- package/lib/src/page.js.map +1 -1
- package/lib/src/rpc-types.d.ts +3 -0
- package/lib/src/vite.d.ts +6 -0
- package/lib/src/vite.js +2 -1
- package/lib/src/vite.js.map +1 -1
- package/lib/tsconfig.tsbuildinfo +1 -1
- package/package.json +15 -10
- package/src/agent-server.ts +73 -0
- package/src/agent.ts +20 -84
- package/src/client.ts +5 -5
- package/src/definition.ts +20 -2
- package/src/index.ts +2 -2
- package/src/js-agent.ts +25 -29
- package/src/node.ts +8 -5
- package/src/page.ts +2 -4
- package/src/rpc-types.ts +4 -0
- package/src/vite.ts +8 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@powersync/diagnostics",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.3",
|
|
4
4
|
"description": "PowerSync DevTools: a devframe definition that serves live PowerSync diagnostics as a Vite DevTools dock, a node dev server, and MCP tools.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/src/index.js",
|
|
@@ -29,6 +29,10 @@
|
|
|
29
29
|
"./node": {
|
|
30
30
|
"types": "./lib/src/node.d.ts",
|
|
31
31
|
"default": "./lib/src/node.js"
|
|
32
|
+
},
|
|
33
|
+
"./agent": {
|
|
34
|
+
"types": "./lib/src/agent.d.ts",
|
|
35
|
+
"default": "./lib/src/agent.js"
|
|
32
36
|
}
|
|
33
37
|
},
|
|
34
38
|
"author": "PowerSync",
|
|
@@ -50,8 +54,8 @@
|
|
|
50
54
|
},
|
|
51
55
|
"homepage": "https://docs.powersync.com",
|
|
52
56
|
"peerDependencies": {
|
|
53
|
-
"@powersync/common": "^2.
|
|
54
|
-
"@powersync/web": "^2.
|
|
57
|
+
"@powersync/common": "^2.5.0",
|
|
58
|
+
"@powersync/web": "^2.6.0",
|
|
55
59
|
"@vitejs/devtools-kit": ">=0.7.5",
|
|
56
60
|
"vite": ">=7.0.0"
|
|
57
61
|
},
|
|
@@ -70,20 +74,21 @@
|
|
|
70
74
|
}
|
|
71
75
|
},
|
|
72
76
|
"dependencies": {
|
|
73
|
-
"@devframes/agentic": "1.
|
|
74
|
-
"devframe": "1.
|
|
77
|
+
"@devframes/agentic": "^1.2.6",
|
|
78
|
+
"devframe": "^1.2.6",
|
|
75
79
|
"zod": "^4.6.5",
|
|
76
|
-
"@powersync/diagnostics-core": "0.0.
|
|
77
|
-
"@powersync/diagnostics-ui": "0.0.
|
|
80
|
+
"@powersync/diagnostics-core": "0.0.3",
|
|
81
|
+
"@powersync/diagnostics-ui": "0.0.3"
|
|
78
82
|
},
|
|
79
83
|
"devDependencies": {
|
|
80
|
-
"@devframes/hub": "1.
|
|
84
|
+
"@devframes/hub": "^1.2.6",
|
|
81
85
|
"@types/node": "^24.0.0",
|
|
82
86
|
"@vitejs/devtools-kit": "^0.7.5",
|
|
83
87
|
"typescript": "^6.0.3",
|
|
84
88
|
"vite": "^7.3.6",
|
|
85
|
-
"@powersync/common": "2.
|
|
86
|
-
"@powersync/
|
|
89
|
+
"@powersync/common": "2.5.0",
|
|
90
|
+
"@powersync/shared-internals": "1.5.0",
|
|
91
|
+
"@powersync/web": "2.6.0"
|
|
87
92
|
},
|
|
88
93
|
"scripts": {
|
|
89
94
|
"build": "tsc -b",
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Serving agents to a devframe node side over an RPC client: a dock script in a web page, or a
|
|
3
|
+
* node process.
|
|
4
|
+
*/
|
|
5
|
+
import type { DevframeRpcClient } from 'devframe/client';
|
|
6
|
+
import type {
|
|
7
|
+
ActionRequest,
|
|
8
|
+
DiagnosticsEvent,
|
|
9
|
+
QueryParams,
|
|
10
|
+
SdkIntegration,
|
|
11
|
+
Unsubscribe
|
|
12
|
+
} from '@powersync/diagnostics-core';
|
|
13
|
+
import { HEARTBEAT_MS } from './constants.js';
|
|
14
|
+
import './rpc-types.js';
|
|
15
|
+
|
|
16
|
+
/** Serves integrations to the node side over one RPC client. */
|
|
17
|
+
export interface AgentServer {
|
|
18
|
+
/** Announces `integration` as `sourceId` and starts forwarding its events. */
|
|
19
|
+
serve(sourceId: string, integration: SdkIntegration, sdk: string): Promise<void>;
|
|
20
|
+
/** Withdraws a served integration. */
|
|
21
|
+
release(sourceId: string): Promise<void>;
|
|
22
|
+
/** Releases everything served through this client. */
|
|
23
|
+
close(): Promise<void>;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Registers the page-side functions the node side calls (`powersync:page-*`) on `rpc`, and returns
|
|
28
|
+
* a server that announces integrations to it. Call once per RPC client.
|
|
29
|
+
*/
|
|
30
|
+
export function createAgentServer(rpc: DevframeRpcClient): AgentServer {
|
|
31
|
+
const served = new Map<string, { integration: SdkIntegration; stop: Unsubscribe }>();
|
|
32
|
+
// The node side only knows this client is alive while it hears from it.
|
|
33
|
+
const heartbeat = setInterval(() => {
|
|
34
|
+
for (const sourceId of served.keys()) void rpc.callEvent('powersync:page-heartbeat', sourceId);
|
|
35
|
+
}, HEARTBEAT_MS);
|
|
36
|
+
(heartbeat as { unref?: () => void }).unref?.();
|
|
37
|
+
|
|
38
|
+
const integrationFor = (sourceId: string): SdkIntegration => {
|
|
39
|
+
const entry = served.get(sourceId);
|
|
40
|
+
if (!entry) throw new Error(`No database "${sourceId}" is served here.`);
|
|
41
|
+
return entry.integration;
|
|
42
|
+
};
|
|
43
|
+
const register = (name: string, handler: (...args: any[]) => unknown) =>
|
|
44
|
+
rpc.client.register({ name, type: 'action', jsonSerializable: true, handler }, true);
|
|
45
|
+
register('powersync:page-query', (id: string, params: QueryParams) => integrationFor(id).runQuery(params));
|
|
46
|
+
register('powersync:page-schema', (id: string) => integrationFor(id).getSchema());
|
|
47
|
+
register('powersync:page-info', (id: string) => integrationFor(id).getInfo());
|
|
48
|
+
register('powersync:page-action', (id: string, request: ActionRequest) => integrationFor(id).action(request));
|
|
49
|
+
|
|
50
|
+
return {
|
|
51
|
+
async serve(sourceId, integration, sdk) {
|
|
52
|
+
await rpc.call('powersync:page-register', sourceId, sdk);
|
|
53
|
+
const stop = await integration.observeEvents((event: DiagnosticsEvent) => {
|
|
54
|
+
void rpc.callEvent('powersync:page-event', sourceId, event);
|
|
55
|
+
});
|
|
56
|
+
served.set(sourceId, { integration, stop });
|
|
57
|
+
},
|
|
58
|
+
async release(sourceId) {
|
|
59
|
+
const entry = served.get(sourceId);
|
|
60
|
+
if (!entry) return;
|
|
61
|
+
served.delete(sourceId);
|
|
62
|
+
entry.stop();
|
|
63
|
+
await entry.integration.close();
|
|
64
|
+
await rpc.call('powersync:page-unregister', sourceId).catch(() => {});
|
|
65
|
+
},
|
|
66
|
+
async close() {
|
|
67
|
+
clearInterval(heartbeat);
|
|
68
|
+
for (const sourceId of [...served.keys()]) {
|
|
69
|
+
await this.release(sourceId);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
}
|
package/src/agent.ts
CHANGED
|
@@ -1,31 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* The agent for a JavaScript host: the `SdkIntegration` built over a live database. This is the
|
|
3
|
+
* package's `./agent` entry, for a host that opens the database and embeds the DevTools page itself;
|
|
4
|
+
* the dock and node entries build their agents here too.
|
|
4
5
|
*/
|
|
5
|
-
import type {
|
|
6
|
-
import type {
|
|
7
|
-
import type
|
|
6
|
+
import type { CommonPowerSyncDatabase } from '@powersync/common';
|
|
7
|
+
import type { CoreDiagnosticsEvent, SdkIntegration, Unsubscribe } from '@powersync/diagnostics-core';
|
|
8
|
+
import { JsAgent, type CoreEventSource } from './js-agent.js';
|
|
9
|
+
import type { BasePowerSyncDatabase } from '@powersync/shared-internals';
|
|
10
|
+
|
|
11
|
+
// The iframe hand-off and the protocol types an embedding host needs, so the host never imports the protocol package.
|
|
12
|
+
export { attachIframe } from '@powersync/diagnostics-core';
|
|
13
|
+
export type {
|
|
8
14
|
ActionRequest,
|
|
9
|
-
|
|
15
|
+
AttachIframeOptions,
|
|
10
16
|
DiagnosticsEvent,
|
|
11
|
-
QueryParams,
|
|
12
17
|
SdkIntegration,
|
|
13
|
-
|
|
18
|
+
SyncState
|
|
14
19
|
} from '@powersync/diagnostics-core';
|
|
15
|
-
import { HEARTBEAT_MS } from './constants.js';
|
|
16
|
-
import { JsAgent, type CoreEventSource } from './js-agent.js';
|
|
17
|
-
import './rpc-types.js';
|
|
18
20
|
|
|
19
21
|
/** The sync client broadcasts core diagnostics events on this channel (see `emitDiagnostics`). */
|
|
20
22
|
const CORE_EVENTS_CHANNEL = 'powersync-diagnostics-events';
|
|
21
23
|
|
|
22
|
-
/**
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
*/
|
|
26
|
-
export interface DiagnosableDatabase extends CommonPowerSyncDatabase {
|
|
27
|
-
readonly connector: PowerSyncBackendConnector | null | undefined;
|
|
28
|
-
readonly connectionOptions: SyncOptions | null | undefined;
|
|
24
|
+
/** The SDK label for the database, or `fallback` on SDK releases that do not report it. */
|
|
25
|
+
export function databaseSdk(database: CommonPowerSyncDatabase, fallback: string): string {
|
|
26
|
+
return (database as Partial<BasePowerSyncDatabase>).sdkName ?? fallback;
|
|
29
27
|
}
|
|
30
28
|
|
|
31
29
|
/** Consumes the core diagnostics events the sync client broadcasts (from a worker or in-process). */
|
|
@@ -43,73 +41,11 @@ class BroadcastCoreEvents implements CoreEventSource {
|
|
|
43
41
|
}
|
|
44
42
|
}
|
|
45
43
|
|
|
46
|
-
/** Builds the JavaScript integration over a live database. */
|
|
47
|
-
export function createIntegration(
|
|
44
|
+
/** Builds the JavaScript integration over a live database. The agent reads the connection from the database itself. */
|
|
45
|
+
export function createIntegration(database: CommonPowerSyncDatabase, sdk: string): SdkIntegration {
|
|
46
|
+
const db = database as BasePowerSyncDatabase;
|
|
48
47
|
return new JsAgent(db, {
|
|
49
48
|
sdk,
|
|
50
|
-
coreEvents: typeof BroadcastChannel === 'function' ? new BroadcastCoreEvents() : undefined
|
|
51
|
-
connection: {
|
|
52
|
-
getConnector: () => db.connector ?? null,
|
|
53
|
-
getConnectionOptions: () => db.connectionOptions ?? null
|
|
54
|
-
}
|
|
49
|
+
coreEvents: typeof BroadcastChannel === 'function' ? new BroadcastCoreEvents() : undefined
|
|
55
50
|
});
|
|
56
51
|
}
|
|
57
|
-
|
|
58
|
-
/** Serves integrations to the node side over one RPC client. */
|
|
59
|
-
export interface AgentServer {
|
|
60
|
-
/** Announces `integration` as `sourceId` and starts forwarding its events. */
|
|
61
|
-
serve(sourceId: string, integration: SdkIntegration, sdk: string): Promise<void>;
|
|
62
|
-
/** Withdraws a served integration. */
|
|
63
|
-
release(sourceId: string): Promise<void>;
|
|
64
|
-
/** Releases everything served through this client. */
|
|
65
|
-
close(): Promise<void>;
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
/**
|
|
69
|
-
* Registers the page-side functions the node side calls (`powersync:page-*`) on `rpc`, and returns
|
|
70
|
-
* a server that announces integrations to it. Call once per RPC client.
|
|
71
|
-
*/
|
|
72
|
-
export function createAgentServer(rpc: DevframeRpcClient): AgentServer {
|
|
73
|
-
const served = new Map<string, { integration: SdkIntegration; stop: Unsubscribe }>();
|
|
74
|
-
// The node side only knows this client is alive while it hears from it.
|
|
75
|
-
const heartbeat = setInterval(() => {
|
|
76
|
-
for (const sourceId of served.keys()) void rpc.callEvent('powersync:page-heartbeat', sourceId);
|
|
77
|
-
}, HEARTBEAT_MS);
|
|
78
|
-
(heartbeat as { unref?: () => void }).unref?.();
|
|
79
|
-
|
|
80
|
-
const integrationFor = (sourceId: string): SdkIntegration => {
|
|
81
|
-
const entry = served.get(sourceId);
|
|
82
|
-
if (!entry) throw new Error(`No database "${sourceId}" is served here.`);
|
|
83
|
-
return entry.integration;
|
|
84
|
-
};
|
|
85
|
-
const register = (name: string, handler: (...args: any[]) => unknown) =>
|
|
86
|
-
rpc.client.register({ name, type: 'action', jsonSerializable: true, handler }, true);
|
|
87
|
-
register('powersync:page-query', (id: string, params: QueryParams) => integrationFor(id).runQuery(params));
|
|
88
|
-
register('powersync:page-schema', (id: string) => integrationFor(id).getSchema());
|
|
89
|
-
register('powersync:page-info', (id: string) => integrationFor(id).getInfo());
|
|
90
|
-
register('powersync:page-action', (id: string, request: ActionRequest) => integrationFor(id).action(request));
|
|
91
|
-
|
|
92
|
-
return {
|
|
93
|
-
async serve(sourceId, integration, sdk) {
|
|
94
|
-
await rpc.call('powersync:page-register', sourceId, sdk);
|
|
95
|
-
const stop = await integration.observeEvents((event: DiagnosticsEvent) => {
|
|
96
|
-
void rpc.callEvent('powersync:page-event', sourceId, event);
|
|
97
|
-
});
|
|
98
|
-
served.set(sourceId, { integration, stop });
|
|
99
|
-
},
|
|
100
|
-
async release(sourceId) {
|
|
101
|
-
const entry = served.get(sourceId);
|
|
102
|
-
if (!entry) return;
|
|
103
|
-
served.delete(sourceId);
|
|
104
|
-
entry.stop();
|
|
105
|
-
await entry.integration.close();
|
|
106
|
-
await rpc.call('powersync:page-unregister', sourceId).catch(() => {});
|
|
107
|
-
},
|
|
108
|
-
async close() {
|
|
109
|
-
clearInterval(heartbeat);
|
|
110
|
-
for (const sourceId of [...served.keys()]) {
|
|
111
|
-
await this.release(sourceId);
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
};
|
|
115
|
-
}
|
package/src/client.ts
CHANGED
|
@@ -5,9 +5,8 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import type { DockClientScriptContext } from '@devframes/hub/client';
|
|
7
7
|
import { observeRegisteredDatabases } from '@powersync/web/devtools';
|
|
8
|
-
import {
|
|
9
|
-
|
|
10
|
-
const SDK = '@powersync/web';
|
|
8
|
+
import { createIntegration, databaseSdk } from './agent.js';
|
|
9
|
+
import { createAgentServer } from './agent-server.js';
|
|
11
10
|
|
|
12
11
|
export default function setup(context: DockClientScriptContext): void {
|
|
13
12
|
const server = createAgentServer(context.rpc);
|
|
@@ -30,7 +29,8 @@ export default function setup(context: DockClientScriptContext): void {
|
|
|
30
29
|
return;
|
|
31
30
|
}
|
|
32
31
|
if (currentId) return;
|
|
33
|
-
|
|
34
|
-
|
|
32
|
+
const sdk = databaseSdk(database, '@powersync/web');
|
|
33
|
+
currentId = `${sdk.replace(/^@powersync\//, '')}-${++counter}`;
|
|
34
|
+
void server.serve(currentId, createIntegration(database, sdk), sdk);
|
|
35
35
|
});
|
|
36
36
|
}
|
package/src/definition.ts
CHANGED
|
@@ -24,9 +24,9 @@ import type {
|
|
|
24
24
|
UploadQueueState
|
|
25
25
|
} from '@powersync/diagnostics-core';
|
|
26
26
|
import { DEVFRAME_ID, HEARTBEAT_MS, UI_ROUTE } from './constants.js';
|
|
27
|
-
import type { SourceInfo } from './rpc-types.js';
|
|
27
|
+
import type { SetupSdk, SourceInfo } from './rpc-types.js';
|
|
28
28
|
|
|
29
|
-
export type { SourceInfo } from './rpc-types.js';
|
|
29
|
+
export type { SetupSdk, SourceInfo } from './rpc-types.js';
|
|
30
30
|
|
|
31
31
|
/** Event types replayed to a UI that subscribes late. `logs` and `core` are not replayed. */
|
|
32
32
|
const SNAPSHOT_TYPES = new Set<DiagnosticsEvent['type']>(['status', 'streams', 'buckets', 'uploadQueue']);
|
|
@@ -77,6 +77,8 @@ class RemoteIntegration implements SdkIntegration {
|
|
|
77
77
|
}
|
|
78
78
|
|
|
79
79
|
const sources = new Map<string, Source>();
|
|
80
|
+
/** The SDKs the entry point that mounted this definition can reach; `null` for all. */
|
|
81
|
+
let setupSdks: SetupSdk[] | null = null;
|
|
80
82
|
/** UI sessions that asked for events, keyed by session id. */
|
|
81
83
|
const observers = new Map<number, DevframeNodeRpcSession>();
|
|
82
84
|
/** The id a page serves a database under, per session, to the id it is listed under here. */
|
|
@@ -209,6 +211,14 @@ function removeSource(sourceId: string): void {
|
|
|
209
211
|
* Serves an integration that lives in this process (a node app's database). Events are pulled from
|
|
210
212
|
* it directly. Returns a function that detaches it.
|
|
211
213
|
*/
|
|
214
|
+
/**
|
|
215
|
+
* Names the SDKs this host can reach, so the UI's "no database" screens explain only those. Each entry
|
|
216
|
+
* point sets it: the Vite plugin, the node server, the Nuxt module.
|
|
217
|
+
*/
|
|
218
|
+
export function setSetupSdks(sdks: SetupSdk[] | null): void {
|
|
219
|
+
setupSdks = sdks?.length ? [...sdks] : null;
|
|
220
|
+
}
|
|
221
|
+
|
|
212
222
|
export async function registerIntegration(
|
|
213
223
|
id: string,
|
|
214
224
|
integration: SdkIntegration,
|
|
@@ -364,6 +374,14 @@ export const definition = defineDevframe({
|
|
|
364
374
|
}
|
|
365
375
|
})
|
|
366
376
|
);
|
|
377
|
+
ps.rpc.register(
|
|
378
|
+
defineRpcFunction({
|
|
379
|
+
name: 'setup-sdks',
|
|
380
|
+
type: 'query',
|
|
381
|
+
jsonSerializable: true,
|
|
382
|
+
handler: (): SetupSdk[] | null => setupSdks
|
|
383
|
+
})
|
|
384
|
+
);
|
|
367
385
|
ps.rpc.register(
|
|
368
386
|
defineRpcFunction({
|
|
369
387
|
name: 'query',
|
package/src/index.ts
CHANGED
|
@@ -2,6 +2,6 @@
|
|
|
2
2
|
// Hosts mount it: `./vite` (Vite DevTools dock) and `./node` (a node app's dev server).
|
|
3
3
|
import './rpc-types.js';
|
|
4
4
|
|
|
5
|
-
export { definition, registerIntegration, uiDistDir } from './definition.js';
|
|
6
|
-
export type { SourceInfo } from './rpc-types.js';
|
|
5
|
+
export { definition, registerIntegration, setSetupSdks, uiDistDir } from './definition.js';
|
|
6
|
+
export type { SetupSdk, SourceInfo } from './rpc-types.js';
|
|
7
7
|
export { UI_ROUTE, DEVFRAME_ID } from './constants.js';
|
package/src/js-agent.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import type {
|
|
2
|
-
|
|
2
|
+
LogLevels,
|
|
3
3
|
LogRecord as SdkLogRecord,
|
|
4
|
-
PowerSyncBackendConnector,
|
|
5
4
|
SyncOptions,
|
|
6
5
|
SyncStatus,
|
|
7
6
|
SyncStreamSubscription
|
|
@@ -18,11 +17,11 @@ import type {
|
|
|
18
17
|
SchemaPayload,
|
|
19
18
|
SdkIntegration,
|
|
20
19
|
StreamActionArgs,
|
|
21
|
-
SyncState,
|
|
22
20
|
Unsubscribe,
|
|
23
21
|
UploadQueueState
|
|
24
22
|
} from '@powersync/diagnostics-core';
|
|
25
23
|
import { toStreamStates, toSyncState } from './sync-state.js';
|
|
24
|
+
import type { BasePowerSyncDatabase, InternalConnector } from '@powersync/shared-internals';
|
|
26
25
|
|
|
27
26
|
/** Delivers the SQLite core's diagnostics events to the agent. How they arrive is runtime-specific. */
|
|
28
27
|
export interface CoreEventSource {
|
|
@@ -30,24 +29,15 @@ export interface CoreEventSource {
|
|
|
30
29
|
dispose(): void;
|
|
31
30
|
}
|
|
32
31
|
|
|
33
|
-
/**
|
|
34
|
-
* Read access to the live connection. The connector and options are not on the database's public
|
|
35
|
-
* interface, so the code that installs the agent (which can see the concrete database) hands them in.
|
|
36
|
-
*/
|
|
37
|
-
export interface ConnectionAccess {
|
|
38
|
-
getConnector(): PowerSyncBackendConnector | null;
|
|
39
|
-
getConnectionOptions(): SyncOptions | null;
|
|
40
|
-
}
|
|
41
|
-
|
|
42
32
|
export interface JsAgentOptions {
|
|
43
33
|
/** A label for the SDK behind this agent, e.g. `@powersync/web`. */
|
|
44
34
|
sdk?: string;
|
|
35
|
+
/** If known, the path to the database */
|
|
36
|
+
databasePath?: string;
|
|
45
37
|
/** Debounce for re-reading bucket stats after internal-table changes. */
|
|
46
38
|
bucketThrottleMs?: number;
|
|
47
39
|
/** Core diagnostics events (per-bucket `target_count`). Omit when core diagnostics are off. */
|
|
48
40
|
coreEvents?: CoreEventSource;
|
|
49
|
-
/** Read access to the live connection; omit if the runtime cannot expose it. */
|
|
50
|
-
connection?: ConnectionAccess;
|
|
51
41
|
}
|
|
52
42
|
|
|
53
43
|
/**
|
|
@@ -62,13 +52,13 @@ export class JsAgent implements SdkIntegration {
|
|
|
62
52
|
/** Debug subscriptions created through `action`, keyed by name + params, so they can be released. */
|
|
63
53
|
private streamHandles = new Map<string, SyncStreamSubscription>();
|
|
64
54
|
// Retained so reconnect / clear work after a disconnect, when the connection no longer exposes them.
|
|
65
|
-
private lastConnector:
|
|
55
|
+
private lastConnector: InternalConnector | null = null;
|
|
66
56
|
private lastConnectionOptions: SyncOptions | null = null;
|
|
67
57
|
// Per-bucket total operation counts from the core diagnostics stream (not stored in ps_buckets).
|
|
68
58
|
private bucketTargets = new Map<string, number>();
|
|
69
59
|
|
|
70
60
|
constructor(
|
|
71
|
-
private db:
|
|
61
|
+
private readonly db: BasePowerSyncDatabase,
|
|
72
62
|
private options: JsAgentOptions = {}
|
|
73
63
|
) {}
|
|
74
64
|
|
|
@@ -86,12 +76,10 @@ export class JsAgent implements SdkIntegration {
|
|
|
86
76
|
}
|
|
87
77
|
|
|
88
78
|
async getInfo(): Promise<ProtocolInfo> {
|
|
89
|
-
const connection = this.options.connection;
|
|
90
|
-
|
|
91
79
|
let endpoint: string | null = null;
|
|
92
80
|
let token: string | null = null;
|
|
93
81
|
try {
|
|
94
|
-
const credentials = await
|
|
82
|
+
const credentials = await this.db.connector?.fetchCredentials?.();
|
|
95
83
|
endpoint = credentials?.endpoint ?? null;
|
|
96
84
|
token = credentials?.token ?? null;
|
|
97
85
|
} catch {
|
|
@@ -113,7 +101,7 @@ export class JsAgent implements SdkIntegration {
|
|
|
113
101
|
// Non-fatal.
|
|
114
102
|
}
|
|
115
103
|
|
|
116
|
-
const connectionOptions =
|
|
104
|
+
const connectionOptions = this.db.connectionOptions ?? null;
|
|
117
105
|
return {
|
|
118
106
|
endpoint,
|
|
119
107
|
token,
|
|
@@ -122,7 +110,8 @@ export class JsAgent implements SdkIntegration {
|
|
|
122
110
|
params: connectionOptions?.params ?? null,
|
|
123
111
|
connected: this.db.currentStatus?.connected ?? false,
|
|
124
112
|
sqliteCoreVersion,
|
|
125
|
-
sdk: this.options.sdk ?? null
|
|
113
|
+
sdk: this.options.sdk ?? null,
|
|
114
|
+
databasePath: this.options.databasePath ?? null
|
|
126
115
|
};
|
|
127
116
|
}
|
|
128
117
|
|
|
@@ -344,17 +333,20 @@ export class JsAgent implements SdkIntegration {
|
|
|
344
333
|
}
|
|
345
334
|
|
|
346
335
|
private captureConnection(): void {
|
|
347
|
-
const
|
|
348
|
-
const connector = connection?.getConnector() ?? null;
|
|
336
|
+
const connector = this.db.connector ?? null;
|
|
349
337
|
if (connector) {
|
|
350
338
|
this.lastConnector = connector;
|
|
351
|
-
this.lastConnectionOptions =
|
|
339
|
+
this.lastConnectionOptions = this.db.connectionOptions ?? null;
|
|
352
340
|
}
|
|
353
341
|
}
|
|
354
342
|
|
|
355
343
|
private async reconnect(): Promise<void> {
|
|
356
344
|
if (this.lastConnector) {
|
|
357
|
-
await this.db.connect(
|
|
345
|
+
await this.db.connectionManager.connect(
|
|
346
|
+
this.lastConnector,
|
|
347
|
+
this.lastConnectionOptions ?? {},
|
|
348
|
+
this.db.schema.toJSON()
|
|
349
|
+
);
|
|
358
350
|
}
|
|
359
351
|
}
|
|
360
352
|
}
|
|
@@ -363,11 +355,15 @@ function streamKey(name: string, params?: Record<string, unknown>): string {
|
|
|
363
355
|
return `${name}|${JSON.stringify(params ?? null)}`;
|
|
364
356
|
}
|
|
365
357
|
|
|
358
|
+
// The SDK's log levels. `typeof LogLevels` makes the compiler hold these to the values in
|
|
359
|
+
// `@powersync/common`, which stays a type-only import because it is an optional peer.
|
|
360
|
+
const LOG_LEVELS: typeof LogLevels = { trace: 10, debug: 20, info: 30, warn: 40, error: 50 };
|
|
361
|
+
|
|
366
362
|
/** Maps a numeric SDK log level to its name. */
|
|
367
363
|
function logLevelName(level: number): string {
|
|
368
|
-
if (level >=
|
|
369
|
-
if (level >=
|
|
370
|
-
if (level >=
|
|
371
|
-
if (level >=
|
|
364
|
+
if (level >= LOG_LEVELS.error) return 'error';
|
|
365
|
+
if (level >= LOG_LEVELS.warn) return 'warn';
|
|
366
|
+
if (level >= LOG_LEVELS.info) return 'info';
|
|
367
|
+
if (level >= LOG_LEVELS.debug) return 'debug';
|
|
372
368
|
return 'trace';
|
|
373
369
|
}
|
package/src/node.ts
CHANGED
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
import type { McpSetting } from 'devframe';
|
|
6
6
|
import { createDevServer } from 'devframe/adapters/dev';
|
|
7
7
|
import { buildOtpAuthUrl } from 'devframe/node/auth';
|
|
8
|
-
import {
|
|
9
|
-
import {
|
|
8
|
+
import type { CommonPowerSyncDatabase } from '@powersync/common';
|
|
9
|
+
import { createIntegration, databaseSdk } from './agent.js';
|
|
10
|
+
import { definition, registerIntegration, setSetupSdks } from './definition.js';
|
|
10
11
|
|
|
11
12
|
export interface EnableDiagnosticsOptions {
|
|
12
13
|
/**
|
|
@@ -23,7 +24,7 @@ export interface EnableDiagnosticsOptions {
|
|
|
23
24
|
auth?: boolean;
|
|
24
25
|
/** Open the browser once the server is up. @default false */
|
|
25
26
|
open?: boolean;
|
|
26
|
-
/** A label for the SDK, shown in the UI. @default '
|
|
27
|
+
/** A label for the SDK, shown in the UI. @default the database's SDK name */
|
|
27
28
|
sdk?: string;
|
|
28
29
|
/** The source id shown in the UI. @default 'node-1' */
|
|
29
30
|
id?: string;
|
|
@@ -56,17 +57,19 @@ export interface DiagnosticsServer {
|
|
|
56
57
|
* ```ts
|
|
57
58
|
* const db = new PowerSyncDatabase({ ... });
|
|
58
59
|
* if (process.env.NODE_ENV !== 'production') {
|
|
60
|
+
* const { enablePowerSyncDiagnostics } = await import('@powersync/diagnostics/node');
|
|
59
61
|
* const devtools = await enablePowerSyncDiagnostics(db);
|
|
60
62
|
* console.log(`PowerSync DevTools: ${devtools.signInUrl}`);
|
|
61
63
|
* }
|
|
62
64
|
* ```
|
|
63
65
|
*/
|
|
64
66
|
export async function enablePowerSyncDiagnostics(
|
|
65
|
-
db:
|
|
67
|
+
db: CommonPowerSyncDatabase,
|
|
66
68
|
options: EnableDiagnosticsOptions = {}
|
|
67
69
|
): Promise<DiagnosticsServer> {
|
|
68
|
-
const sdk = options.sdk ?? '@powersync/node';
|
|
70
|
+
const sdk = options.sdk ?? databaseSdk(db, '@powersync/node');
|
|
69
71
|
const detach = await registerIntegration(options.id ?? 'node-1', createIntegration(db, sdk), sdk);
|
|
72
|
+
setSetupSdks(['node']);
|
|
70
73
|
const auth = options.auth ?? true;
|
|
71
74
|
const server = await createDevServer(definition, {
|
|
72
75
|
port: options.port ?? 0,
|
package/src/page.ts
CHANGED
|
@@ -11,9 +11,7 @@ import {
|
|
|
11
11
|
type SdkIntegration
|
|
12
12
|
} from '@powersync/diagnostics-core';
|
|
13
13
|
import { observeRegisteredDatabases } from '@powersync/web/devtools';
|
|
14
|
-
import { createIntegration } from './agent.js';
|
|
15
|
-
|
|
16
|
-
const SDK = '@powersync/web';
|
|
14
|
+
import { createIntegration, databaseSdk } from './agent.js';
|
|
17
15
|
|
|
18
16
|
/**
|
|
19
17
|
* Serves the app's first live database to any iframe that asks. Call once per page.
|
|
@@ -29,7 +27,7 @@ export function serveDiagnostics(): () => void {
|
|
|
29
27
|
for (const stop of stops) stop();
|
|
30
28
|
stops.clear();
|
|
31
29
|
void integration?.close();
|
|
32
|
-
integration = next ? createIntegration(next,
|
|
30
|
+
integration = next ? createIntegration(next, databaseSdk(next, '@powersync/web')) : null;
|
|
33
31
|
});
|
|
34
32
|
|
|
35
33
|
const onMessage = (event: MessageEvent) => {
|
package/src/rpc-types.ts
CHANGED
|
@@ -21,10 +21,14 @@ export interface SourceInfo {
|
|
|
21
21
|
sdk: string | null;
|
|
22
22
|
}
|
|
23
23
|
|
|
24
|
+
/** An SDK the UI's "no database" screens can explain, the same names the UI takes as `sdks`. */
|
|
25
|
+
export type SetupSdk = 'web' | 'nuxt' | 'node' | 'dart';
|
|
26
|
+
|
|
24
27
|
declare module 'devframe/types' {
|
|
25
28
|
/** Functions the node side serves; called by the UI, by agents over MCP, and by pages announcing a database. */
|
|
26
29
|
interface DevframeRpcServerFunctions {
|
|
27
30
|
'powersync:sources': () => SourceInfo[];
|
|
31
|
+
'powersync:setup-sdks': () => SetupSdk[] | null;
|
|
28
32
|
'powersync:query': (params: QueryParams, sourceId?: string | null) => Promise<QueryResult>;
|
|
29
33
|
'powersync:schema': (sourceId?: string | null) => Promise<SchemaPayload>;
|
|
30
34
|
'powersync:info': (sourceId?: string | null) => Promise<ProtocolInfo>;
|
package/src/vite.ts
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node';
|
|
2
2
|
import type { Plugin } from 'vite';
|
|
3
|
-
import { definition } from './definition.js';
|
|
3
|
+
import { definition, setSetupSdks } from './definition.js';
|
|
4
|
+
import type { SetupSdk } from './rpc-types.js';
|
|
4
5
|
|
|
5
6
|
const PLUGIN_NAME = 'powersync-diagnostics';
|
|
6
7
|
|
|
7
8
|
export interface PowerSyncDevToolsOptions {
|
|
8
9
|
/** Title of the dock entry. */
|
|
9
10
|
title?: string;
|
|
11
|
+
/**
|
|
12
|
+
* The SDKs the setup screen explains when no database is attached. @default ['web']. A framework
|
|
13
|
+
* module built on this plugin passes its own, e.g. `['nuxt', 'web']`.
|
|
14
|
+
*/
|
|
15
|
+
sdks?: SetupSdk[];
|
|
10
16
|
}
|
|
11
17
|
|
|
12
18
|
/**
|
|
@@ -25,6 +31,7 @@ export interface PowerSyncDevToolsOptions {
|
|
|
25
31
|
* ```
|
|
26
32
|
*/
|
|
27
33
|
export default function powersyncDevtools(options: PowerSyncDevToolsOptions = {}): Plugin {
|
|
34
|
+
setSetupSdks(options.sdks ?? ['web']);
|
|
28
35
|
const plugin = createPluginFromDevframe(definition, { name: PLUGIN_NAME });
|
|
29
36
|
plugin.devtools!.setup = async (context) => {
|
|
30
37
|
// Frameworks that run a second Vite server for server-side rendering set it up too; the browser
|