@powersync/node 0.2.2 → 0.4.0

package/README.md

@@ -56,6 +56,22 @@ contains everything you need to know to get started implementing PowerSync in yo
 
 A simple example using `@powersync/node` is available in the [`demos/example-node/`](../demos/example-node) directory.
 
+# Proxy Support
+
+This SDK supports HTTP, HTTPS, and WebSocket proxies via environment variables.
+
+## HTTP Connection Method
+
+Internally we probe the http environment variables and apply it to fetch requests ([undici](https://www.npmjs.com/package/undici/v/5.6.0))
+
+- Set the `HTTPS_PROXY` or `HTTP_PROXY` environment variable to automatically route HTTP requests through a proxy.
+
+## WEB Socket Connection Method
+
+Internally the [proxy-agent](https://www.npmjs.com/package/proxy-agent) dependency for WebSocket proxies, which has its own internal code for automatically picking up the appropriate environment variables:
+
+- Set the `WS_PROXY` or `WSS_PROXY` environment variable to route the webocket connections through a proxy.
+
 # Found a bug or need help?
 
 - Join our [Discord server](https://discord.gg/powersync) where you can browse topics from our community, ask questions, share feedback, or just say hello :)

package/download_core.js

@@ -6,7 +6,7 @@ import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
 import { exit } from 'node:process';
 
-const version = '0.3.11';
+const version = '0.3.14';
 
 const platform = OS.platform();
 let destination;

package/lib/db/PowerSyncDatabase.d.ts

@@ -1,8 +1,23 @@
-import { AbstractPowerSyncDatabase, AbstractStreamingSyncImplementation, BucketStorageAdapter, DBAdapter, PowerSyncBackendConnector, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithSettings, SQLOpenFactory } from '@powersync/common';
+import { AbstractPowerSyncDatabase, AbstractRemoteOptions, AbstractStreamingSyncImplementation, AdditionalConnectionOptions, BucketStorageAdapter, DBAdapter, PowerSyncBackendConnector, PowerSyncConnectionOptions, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithSettings, SQLOpenFactory } from '@powersync/common';
 import { NodeSQLOpenOptions } from './options.js';
+import { Dispatcher } from 'undici';
 export type NodePowerSyncDatabaseOptions = PowerSyncDatabaseOptions & {
     database: DBAdapter | SQLOpenFactory | NodeSQLOpenOptions;
+    /**
+     * Options to override how the SDK will connect to the sync service.
+     *
+     * This option is intended to be used for internal tests.
+     */
+    remoteOptions?: Partial<AbstractRemoteOptions>;
+};
+export type NodeAdditionalConnectionOptions = AdditionalConnectionOptions & {
+    /**
+     * Optional custom dispatcher for HTTP connections (e.g. using undici).
+     * Only used when the connection method is SyncStreamConnectionMethod.HTTP
+     */
+    dispatcher?: Dispatcher;
 };
+export type NodePowerSyncConnectionOptions = PowerSyncConnectionOptions & NodeAdditionalConnectionOptions;
 /**
  * A PowerSync database which provides SQLite functionality
  * which is automatically synced.
@@ -25,5 +40,8 @@ export declare class PowerSyncDatabase extends AbstractPowerSyncDatabase {
      */
     protected openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
     protected generateBucketStorageAdapter(): BucketStorageAdapter;
-    protected generateSyncStreamImplementation(connector: PowerSyncBackendConnector): AbstractStreamingSyncImplementation;
+    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions & {
+        dispatcher?: Dispatcher;
+    }): Promise<void>;
+    protected generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: NodeAdditionalConnectionOptions): AbstractStreamingSyncImplementation;
 }

package/lib/db/PowerSyncDatabase.js

@@ -32,8 +32,14 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
     generateBucketStorageAdapter() {
         return new SqliteBucketStorage(this.database, AbstractPowerSyncDatabase.transactionMutex);
     }
-    generateSyncStreamImplementation(connector) {
-        const remote = new NodeRemote(connector);
+    connect(connector, options) {
+        return super.connect(connector, options);
+    }
+    generateSyncStreamImplementation(connector, options) {
+        const remote = new NodeRemote(connector, this.options.logger, {
+            dispatcher: options.dispatcher,
+            ...this.options.remoteOptions
+        });
         return new NodeStreamingSyncImplementation({
             adapter: this.bucketStorageAdapter,
             remote,

package/lib/db/RemoteConnection.d.ts

@@ -11,6 +11,11 @@ export declare class RemoteConnection implements LockContext {
     private readonly comlink;
     readonly database: Remote<AsyncDatabase>;
     constructor(worker: Worker, comlink: Remote<AsyncDatabaseOpener>, database: Remote<AsyncDatabase>);
+    /**
+     * Runs the inner function, but appends the stack trace where this function was called. This is useful for workers
+     * because stack traces from worker errors are otherwise unrelated to the application issue that has caused them.
+     */
+    private recoverTrace;
     executeBatch(query: string, params?: any[][]): Promise<QueryResult>;
     execute(query: string, params?: any[] | undefined): Promise<QueryResult>;
     executeRaw(query: string, params?: any[] | undefined): Promise<any[][]>;

package/lib/db/RemoteConnection.js

@@ -12,16 +12,39 @@ export class RemoteConnection {
         this.comlink = comlink;
         this.database = database;
     }
-    async executeBatch(query, params = []) {
-        const result = await this.database.executeBatch(query, params ?? []);
-        return RemoteConnection.wrapQueryResult(result);
+    /**
+     * Runs the inner function, but appends the stack trace where this function was called. This is useful for workers
+     * because stack traces from worker errors are otherwise unrelated to the application issue that has caused them.
+     */
+    async recoverTrace(inner) {
+        const trace = {};
+        Error.captureStackTrace(trace);
+        try {
+            return await inner();
+        }
+        catch (e) {
+            if (e instanceof Error && e.stack) {
+                e.stack += trace.stack;
+            }
+            throw e;
+        }
+    }
+    executeBatch(query, params = []) {
+        return this.recoverTrace(async () => {
+            const result = await this.database.executeBatch(query, params ?? []);
+            return RemoteConnection.wrapQueryResult(result);
+        });
     }
-    async execute(query, params) {
-        const result = await this.database.execute(query, params ?? []);
-        return RemoteConnection.wrapQueryResult(result);
+    execute(query, params) {
+        return this.recoverTrace(async () => {
+            const result = await this.database.execute(query, params ?? []);
+            return RemoteConnection.wrapQueryResult(result);
+        });
     }
-    async executeRaw(query, params) {
-        return await this.database.executeRaw(query, params ?? []);
+    executeRaw(query, params) {
+        return this.recoverTrace(async () => {
+            return await this.database.executeRaw(query, params ?? []);
+        });
     }
     async getAll(sql, parameters) {
         const res = await this.execute(sql, parameters);

package/lib/sync/stream/NodeRemote.d.ts

@@ -1,10 +1,14 @@
-import { ILogger } from 'js-logger';
-import { AbstractRemote, AbstractRemoteOptions, BSONImplementation, RemoteConnector } from '@powersync/common';
+import { type ILogger, AbstractRemote, AbstractRemoteOptions, BSONImplementation, RemoteConnector } from '@powersync/common';
+import { Dispatcher } from 'undici';
 export declare const STREAMING_POST_TIMEOUT_MS = 30000;
+export type NodeRemoteOptions = AbstractRemoteOptions & {
+    dispatcher?: Dispatcher;
+};
 export declare class NodeRemote extends AbstractRemote {
     protected connector: RemoteConnector;
     protected logger: ILogger;
-    constructor(connector: RemoteConnector, logger?: ILogger, options?: Partial<AbstractRemoteOptions>);
+    constructor(connector: RemoteConnector, logger?: ILogger, options?: Partial<NodeRemoteOptions>);
+    protected createSocket(url: string): globalThis.WebSocket;
     getUserAgent(): string;
     getBSON(): Promise<BSONImplementation>;
 }

package/lib/sync/stream/NodeRemote.js

@@ -1,6 +1,9 @@
 import * as os from 'node:os';
 import { AbstractRemote, DEFAULT_REMOTE_LOGGER, FetchImplementationProvider } from '@powersync/common';
 import { BSON } from 'bson';
+import Agent from 'proxy-agent';
+import { EnvHttpProxyAgent } from 'undici';
+import { WebSocket } from 'ws';
 export const STREAMING_POST_TIMEOUT_MS = 30_000;
 class NodeFetchProvider extends FetchImplementationProvider {
     getFetch() {
@@ -11,13 +14,27 @@ export class NodeRemote extends AbstractRemote {
     connector;
     logger;
     constructor(connector, logger = DEFAULT_REMOTE_LOGGER, options) {
+        // EnvHttpProxyAgent automatically uses relevant env vars for HTTP
+        const dispatcher = options?.dispatcher ?? new EnvHttpProxyAgent();
         super(connector, logger, {
-            ...(options ?? {}),
-            fetchImplementation: options?.fetchImplementation ?? new NodeFetchProvider()
+            fetchImplementation: options?.fetchImplementation ?? new NodeFetchProvider(),
+            fetchOptions: {
+                dispatcher
+            },
+            ...(options ?? {})
         });
         this.connector = connector;
         this.logger = logger;
     }
+    createSocket(url) {
+        return new WebSocket(url, {
+            // Automatically uses relevant env vars for web sockets
+            agent: new Agent.ProxyAgent(),
+            headers: {
+                'User-Agent': this.getUserAgent()
+            }
+        }); // This is compatible in Node environments
+    }
     getUserAgent() {
         return [
             super.getUserAgent(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/node",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -36,14 +36,17 @@
   },
   "homepage": "https://docs.powersync.com/",
   "peerDependencies": {
-    "@powersync/common": "^1.27.1"
+    "@powersync/common": "^1.29.0"
   },
   "dependencies": {
     "@powersync/better-sqlite3": "^0.1.1",
     "async-lock": "^1.4.0",
     "bson": "^6.6.0",
     "comlink": "^4.4.2",
-    "@powersync/common": "1.27.1"
+    "proxy-agent": "^6.5.0",
+    "undici": "^7.8.0",
+    "ws": "^8.18.1",
+    "@powersync/common": "1.29.0"
   },
   "devDependencies": {
     "@types/async-lock": "^1.4.0",