@dittolive/ditto 4.5.1 → 4.5.2-rc.3

package/react-native/src/sources/subscription-manager.ts

@@ -69,7 +69,8 @@ export class SubscriptionManager {
       for (const subscriptionID in this.subscriptions) {
         const subscription = this.subscriptions[subscriptionID].deref()
         if (subscription != null) {
-
+          // This doesn't call `Subscription.cancel()` because that is not
+          // async and we want to wait for all subscriptions to be removed.
           this.remove(subscription)
         }
       }

package/react-native/src/sources/subscription.ts

@@ -51,6 +51,7 @@ export class Subscription {
 
   /** @internal */
   constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: FFI.OrderBy[], limit: number, offset: number) {
+    // Query should be validated at this point.
     this.query = query
     this.queryArgsCBOR = queryArgsCBOR
     this.collection = collection

package/react-native/src/sources/sync.ts

@@ -28,6 +28,11 @@ export type SyncParameters = {
 
 /** @internal */
 export type SyncState = {
+  // NOTE: we can get away with just an effective transport config for now,
+  // but this is meant to carry more state if need be. Whenever possible,
+  // prefer putting logic into the `stateFrom()` function together with some
+  // flags here and keep the `updateXXX()` to just diffing and updating the
+  // low-level transports machinery.
   readonly underlyingSyncParameters: SyncParameters
   readonly effectiveTransportConfig: TransportConfig
 }
@@ -106,7 +111,7 @@ export class Sync {
 
   /** @internal */
   get parameters(): SyncParameters {
-    return this._parameters
+    return this.state.underlyingSyncParameters
   }
 
   /** @internal */
@@ -116,7 +121,6 @@ export class Sync {
     const parameters = { identity, transportConfig, ditto, isWebValid: false, isX509Valid: false, isSyncActive: false }
 
     this.ditto = ditto
-    this._parameters = parameters
     this.state = stateFrom(parameters)
 
     FFI.transportsInit()
@@ -154,11 +158,12 @@ export class Sync {
 
     const newSyncSubscriptions = [...this.subscriptions]
     newSyncSubscriptions.splice(indexToDelete, 1)
+    // @ts-expect-error modifying readonly property
     this.subscriptions = Object.freeze(newSyncSubscriptions)
 
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     this.ditto.deferClose(() => {
-      // prettier-ignor
+      // prettier-ignore
       mapFFIErrors(
         () => FFI.tryExperimentalRemoveDQLSubscription(dittoHandle.deref(), syncSubscription.queryString, syncSubscription.queryArgumentsCBOR)
       )
@@ -168,10 +173,16 @@ export class Sync {
 
   /** @internal */
   update(parameters: SyncParameters) {
-    this._parameters = { ...parameters }
+    // NOTE: updating is a two-step process. Given all parameters, we
+    // first compute the final "state" we want the transports stuff to
+    // be in via the `stateFrom()` function. We then take that "desired" state
+    // and feed it into the various update methods, which essentially perform
+    // a diff on the state before and after, and update the low-level transports
+    // machinery accordingly.
 
     const stateOld = this.state
-    const stateNew = stateFrom(this.parameters)
+    const stateNew = stateFrom(parameters)
+
     this.updatePeerToPeerBluetoothLE(stateOld, stateNew)
     this.updatePeerToPeerAWDL(stateOld, stateNew)
     this.updatePeerToPeerLAN(stateOld, stateNew)
@@ -181,6 +192,7 @@ export class Sync {
     this.updateConnectWebsocketURLs(stateOld, stateNew)
     this.updateGlobal(stateOld, stateNew)
     this.updateConnectRetryInterval(stateOld, stateNew)
+
     this.state = stateNew
   }
 
@@ -194,15 +206,14 @@ export class Sync {
       subscription.cancel()
     }
 
-
+    // Nothing to do, when sync is stopped, this object should be
+    // already be cleaned up properly.
   }
 
   // ------------------------------------------------------------ Private ------
 
   private state: SyncState
 
-  private _parameters: SyncParameters
-
   private bluetoothLETransportPointer: FFI.Pointer<'DittoTransportsBLE_t'> | null = null
   private awdlTransportPointer: FFI.Pointer<'DittoTransportsAWDL_t'> | null = null
   private lanTransportPointer: FFI.Pointer<'DittoTransportsLAN_t'> | null = null
@@ -210,6 +221,7 @@ export class Sync {
   private mdnsServerAdvertiserPointer: FFI.Pointer<'DittoTransportsMdnsServer_t'> | null = null
 
   private updatePeerToPeerBluetoothLE(stateOld: SyncState, stateNew: SyncState) {
+    // Updating BLE transport is a no-op outside of Node.js & React Native.
     if (!Environment.isNodeBuild && !Environment.isReactNativeBuild) return
 
     const ditto = this.ditto
@@ -224,7 +236,6 @@ export class Sync {
       if (shouldStart && this.bluetoothLETransportPointer) throw new Error(`Internal inconsistency, when starting BLE transport, no BLE transport pointer should exist.`)
       if (shouldStop && !this.bluetoothLETransportPointer) throw new Error(`Internal inconsistency, when stopping BLE transport, a BLE transport pointer should exist.`)
 
-
       if (process.platform === 'linux' || process.platform === 'win32') {
         if (shouldStart) {
           const clientTransport = FFI.dittoAddInternalBLEClientTransport(dittoHandle.deref())
@@ -249,6 +260,7 @@ export class Sync {
       }
 
       if (shouldStop) {
+        // null check is performed above
         FFI.transportsBLEDestroy(this.bluetoothLETransportPointer as FFI.Pointer<FFI.TransportBluetooth>)
         this.bluetoothLETransportPointer = null
       }
@@ -256,6 +268,7 @@ export class Sync {
   }
 
   private updatePeerToPeerAWDL(stateOld: SyncState, stateNew: SyncState) {
+    // Updating AWDL transport is a no-op outside of Node.js & React Native.
     if (!Environment.isNodeBuild && !Environment.isReactNativeBuild) return
 
     const ditto = this.ditto
@@ -275,6 +288,7 @@ export class Sync {
       }
 
       if (shouldStop) {
+        // null check is performed above
         FFI.transportsAWDLDestroy(this.awdlTransportPointer as FFI.Pointer<FFI.TransportAWDL>)
         this.awdlTransportPointer = null
       }
@@ -282,6 +296,7 @@ export class Sync {
   }
 
   private updatePeerToPeerLAN(stateOld: SyncState, stateNew: SyncState) {
+    // Updating LAN transport currently only works with Node.js & React Native.
     if (!Environment.isNodeBuild && !Environment.isReactNativeBuild) return
 
     const ditto = this.ditto
@@ -289,8 +304,7 @@ export class Sync {
     ditto.deferClose(() => {
       const lanOld = stateOld.effectiveTransportConfig.peerToPeer.lan
       const lanNew = stateNew.effectiveTransportConfig.peerToPeer.lan
-
-
+      
       if (process.platform === 'win32' || process.platform === 'linux') {
         if (lanOld.isEnabled) {
           if (lanOld.isMdnsEnabled) {
@@ -322,6 +336,8 @@ export class Sync {
         return
       }
 
+      // IDEA: move the logic for this dance into stateFrom() signal
+      // via some additional state signaling the actions here.
 
       if (lanOld.isEnabled) {
         if (lanOld.isMdnsEnabled) {
@@ -419,30 +435,89 @@ export class Sync {
 }
 
 /**
+ * Computes the effective transport config given a desired transport config and
+ * some additional state.
+ *
+ * Disables all transports that are unavailable due to the runtime environment
+ * or authentication requirements. Adds websocket URL for Ditto Cloud if
+ * enabled.
+ *
+ * Throws if the target transport config enables sync but contains transports
+ * that are not available in the current environment. Does not throw when
+ * transports are enabled but not available due to authentication requirements.
+ *
  * @private
  */
 function stateFrom(parameters: SyncParameters): SyncState {
-  const ditto = parameters.ditto
-  const dittoHandle = Bridge.ditto.handleFor(ditto)
-  return ditto.deferClose(() => {
+  // IMPORTANT: this function maps a set of sync parameters to an effective
+  // transport config plus some extra state where need be. Make sure
+  // to keep this function free of side-effects.
 
+  const identity = parameters.identity
 
-    const transportConfig = parameters.transportConfig.copy()
-    const identity = parameters.identity
+  const isSyncActive = parameters.isSyncActive
+  const isX509Valid = parameters.isX509Valid
+  const isWebValid = parameters.isWebValid
 
-    const isSyncActive = parameters.isSyncActive
-    const isX509Valid = parameters.isX509Valid
-    const isWebValid = parameters.isWebValid
+  let appID
+  let customDittoCloudURL
+  let isDittoCloudSyncEnabled = false
 
-    let appID
-    let customDittoCloudURL
-    let isDittoCloudSyncEnabled = false
+  if (identity.type === 'onlinePlayground' || identity.type === 'onlineWithAuthentication') {
+    // NOTE: enableDittoCloudSync is true by default for any online identity.
+    appID = identity.appID
+    customDittoCloudURL = identity.customDittoCloudURL ?? null
+    isDittoCloudSyncEnabled = identity.enableDittoCloudSync ?? true
+  }
 
-    if (identity.type === 'onlinePlayground' || identity.type === 'onlineWithAuthentication') {
-      appID = identity.appID
-      customDittoCloudURL = identity.customDittoCloudURL ?? null
-      isDittoCloudSyncEnabled = identity.enableDittoCloudSync ?? true
-    }
+  validateEnabledTransportsAvailable(parameters.ditto, parameters.transportConfig)
+
+  const transportConfig = parameters.transportConfig.copy()
+
+  if (!isSyncActive || !isX509Valid) {
+    transportConfig.peerToPeer.bluetoothLE.isEnabled = false
+    transportConfig.peerToPeer.awdl.isEnabled = false
+    transportConfig.peerToPeer.lan.isEnabled = false
+    transportConfig.listen.tcp.isEnabled = false
+    transportConfig.connect.tcpServers = []
+  }
+
+  if (!isSyncActive || !isWebValid) {
+    transportConfig.connect.websocketURLs = []
+  }
+
+  if (!isSyncActive) {
+    transportConfig.listen.http.isEnabled = false
+  }
+
+  // NOTE: we have to smuggle in an additional Ditto Cloud websocket URL to
+  // connect to if cloud sync is enabled.
+  if (isSyncActive && isWebValid && isDittoCloudSyncEnabled) {
+    // @ts-ignore To fix this type error, refactor using a switch
+    // statement, c.f.
+    // https://github.com/getditto/ditto/blob/d35b6c1cb280cdd6368d14137c97609b9b9b9296/js/sources/sync.ts#L488
+    const dittoCloudURL = customDittoCloudURL ?? defaultDittoCloudURL(appID)
+    transportConfig.connect.websocketURLs.push(dittoCloudURL)
+  }
+
+  return {
+    underlyingSyncParameters: parameters,
+    effectiveTransportConfig: transportConfig.freeze(),
+  }
+}
+
+/**
+ * Validate that all enabled transports are available in the current environment
+ * and throw an error if not.
+ *
+ * @private
+ */
+function validateEnabledTransportsAvailable(ditto: Ditto, transportConfig: TransportConfig) {
+  const dittoHandle = Bridge.ditto.handleFor(ditto)
+  return ditto.deferClose(() => {
+    // - BLE
+    // - AWDL
+    // - LAN / mDNS
 
     const unavailableButEnabledP2PTransports = []
 
@@ -466,30 +541,19 @@ function stateFrom(parameters: SyncParameters): SyncState {
       throw new Error(`The following P2P transports are enabled in the transport config but are not supported in the current environment: ${unavailableButEnabledP2PTransports.join(', ')}`)
     }
 
-    if (!isSyncActive || !isX509Valid) {
-      transportConfig.peerToPeer.bluetoothLE.isEnabled = false
-      transportConfig.peerToPeer.awdl.isEnabled = false
-      transportConfig.peerToPeer.lan.isEnabled = false
-      transportConfig.listen.tcp.isEnabled = false
-      transportConfig.connect.tcpServers = []
-    }
-
-    if (!isSyncActive || !isWebValid) {
-      transportConfig.connect.websocketURLs = []
-    }
+    // - Websocket / HTTP
+    // - TCP
 
-    if (!isSyncActive) {
-      transportConfig.listen.http.isEnabled = false
+    if (transportConfig.connect.tcpServers.length > 0 && Environment.isWebBuild) {
+      throw new Error(`The transport config contains TCP servers, but this transport is not supported in web environments`)
     }
 
-    if (isSyncActive && isWebValid && isDittoCloudSyncEnabled) {
-      const dittoCloudURL = customDittoCloudURL ?? defaultDittoCloudURL(appID)
-      transportConfig.connect.websocketURLs.push(dittoCloudURL)
+    if (transportConfig.listen.http.isEnabled && Environment.isWebBuild) {
+      throw new Error(`The transport config contains an HTTP listener, which is not supported in web environments`)
     }
 
-    return {
-      underlyingSyncParameters: parameters,
-      effectiveTransportConfig: transportConfig.freeze(),
+    if (transportConfig.listen.tcp.isEnabled && Environment.isWebBuild) {
+      throw new Error(`The transport config contains a TCP listener, which is not supported in web environments`)
     }
   })
 }

package/react-native/src/sources/transport-config.ts

@@ -122,6 +122,7 @@ export function transportConfigToSerializable(config: TransportConfig): any {
     },
   }
 
+  // Only set the optional properties if they are not undefined
   if (listen.http.staticContentPath) {
     serialized.listen.http['static_content_path'] = listen.http.staticContentPath
   }
@@ -396,6 +397,7 @@ export class TransportConfig {
    */
   static areListenTCPsEqual(left: TransportConfigListenTCP, right: TransportConfigListenTCP): boolean {
     /* eslint-disable */
+    // prettier-ignore
     return (
       left.isEnabled === right.isEnabled &&
       left.interfaceIP === right.interfaceIP &&

package/react-native/src/sources/websocket-client.ts

@@ -2,5 +2,6 @@
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
 
+
 /** @internal */
 export class WebsocketClient {}

package/react-native/src/sources/write-transaction-pending-id-specific-operation.ts

@@ -53,6 +53,8 @@ export class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpe
       const mutableDocument = Bridge.mutableDocument.bridge(documentX, () => new MutableDocument())
       closure(mutableDocument)
 
+      // Ownership is transferred back to the FFI layer via collectionUpdate(),
+      // we therefore need to explicitly unregister the instance.
       Bridge.mutableDocument.unregister(mutableDocument)
 
       await FFI.collectionUpdate(dittoHandle.deref(), this.collection.name, transaction.writeTransactionPointer, documentX)

package/react-native/src/sources/write-transaction.ts

@@ -37,12 +37,14 @@ export interface WriteTransactionResult {
  * Create a write transaction using {@link Store.write | ditto.store.write}.
  */
 export class WriteTransaction {
+  // Pointer to internal C transaction through FFI.
   /** @internal */
   readonly writeTransactionPointer: FFI.Pointer<FFI.FFIWriteTransaction>
 
   /** @internal */
   readonly ditto: Ditto
 
+  // All documents affected by writes in this transaction are collected here.
   readonly results: WriteTransactionResult[]
 
   /**

package/types/ditto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ditto.d.ts","sources":[],"sourcesContent":[],"names":[],"mappings":""}