@dittolive/ditto 4.4.4 → 4.5.0

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

@@ -0,0 +1,216 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { Subscription } from './subscription'
+import { LiveQuery } from './live-query'
+import { Document, MutableDocument } from './document'
+import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
+import { BasePendingIDSpecificOperation } from './base-pending-id-specific-operation'
+import { SingleDocumentLiveQueryEvent } from './live-query-event'
+
+import type { DocumentID } from './document-id'
+import type { UpdateResult } from './update-result'
+import type { Collection } from './collection'
+
+
+/**
+ * The closure that is called whenever a single documunent covered by a
+ * live query changes.
+ */
+export type SingleObservationHandler = (document: Document | null, event: SingleDocumentLiveQueryEvent, signalNext?: () => void) => void | Promise<void>
+
+// -----------------------------------------------------------------------------
+
+/**
+ * These objects are returned when using {@link Collection.findByID | findByID()}
+ * functionality on {@link Collection | collections}.
+ *
+ * You can either call {@link exec | exec()} on the  object to get an immediate
+ * return value, or you can establish either a live query or a subscription,
+ * which both work over time.
+ *
+ * A live query, established by calling
+ * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, will notify
+ * you every time there's an update to the document with the ID you provided in
+ * the preceding {@link Collection.findByID | findByID()} call.
+ *
+ * A subscription, established by calling {@link PendingIDSpecificOperation.subscribe | subscribe()}, will
+ * act as a signal to other peers that you would like to receive updates from
+ * them about the document with the ID you provided in the preceding
+ * {@link Collection.findByID | findByID()} call.
+ *
+ * Update and remove functionality is also exposed through this object.
+ */
+export class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
+  async remove(): Promise<boolean> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const didRemove = await FFI.collectionRemove(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return didRemove
+      })
+    })
+  }
+
+  async evict(): Promise<boolean> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const didEvict = await FFI.collectionEvict(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return didEvict
+      })
+    })
+  }
+
+  async update(closure: (document: MutableDocument) => void): Promise<UpdateResult[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      const readTransactionX = await FFI.readTransaction(dittoHandle.deref())
+      const documentX = await FFI.collectionGet(dittoHandle.deref(), this.collection.name, this.documentIDCBOR, readTransactionX)
+      FFI.readTransactionFree(readTransactionX)
+
+      if (!documentX) throw new Error(`Can't update, document with ID '${this.documentID.toString()}' not found in collection named '${this.collection.name}'`)
+
+      const mutableDocument = Bridge.mutableDocument.bridge(documentX, () => new MutableDocument())
+      closure(mutableDocument)
+
+
+      Bridge.mutableDocument.unregister(mutableDocument)
+
+      const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+      await FFI.collectionUpdate(dittoHandle.deref(), this.collection.name, writeTransactionX, documentX)
+      await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+
+      return mutableDocument['@ditto.updateResults'].slice()
+    })
+  }
+
+  /**
+   * Enables you to subscribe to changes that occur in relation to a document
+   * remotely.
+   *
+   * Having a subscription acts as a signal to other peers that you are
+   * interested in receiving updates when local or remote changes are made to
+   * the relevant document.
+   *
+   * The returned {@link Subscription} object must be kept in scope for as long
+   * as you want to keep receiving updates.
+   *
+   * @returns A {@link Subscription} object that must be kept in scope for as
+   * long as you want to keep receiving updates for the document.
+   */
+  subscribe(): Subscription {
+    const subscription = new Subscription(this.collection as Collection, this.query, null, [], -1, 0)
+    this.collection.store.ditto.subscriptionManager.add(subscription)
+    return subscription
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to a document
+   * locally.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+   * document ID.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long
+   * as you want the provided `handler` to be called when an update
+   * occurs.
+   *
+   * @param handler A block that will be called every time there is a
+   * transaction committed to the store that involves a modification to the
+   * document with the relevant ID in the collection that
+   * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
+   *
+   * @returns A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocal(handler: SingleObservationHandler): LiveQuery {
+    return this._observe(handler, false)
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to a document
+   * locally and to signal when you are ready for the live query to deliver
+   * the next event.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+   * document ID.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long
+   * as you want the provided `handler` to be called when an update
+   * occurs.
+   *
+   * @param handler A block that will be called every time there is a
+   * transaction committed to the store that involves a modification to the
+   * document with the relevant ID in the collection that
+   * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
+   *
+   * @returns A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocalWithNextSignal(handler: SingleObservationHandler): LiveQuery {
+    return this._observe(handler, true)
+  }
+
+  /** @internal */
+  constructor(documentID: DocumentID, collection: Collection) {
+    super(documentID, collection)
+  }
+
+  /** @internal */
+  _observe(handler: SingleObservationHandler, waitForNextSignal: boolean): LiveQuery {
+    const liveQuery = new LiveQuery(this.query, null, null, [], -1, 0, this.collection as Collection, (documents, event, signalNext) => {
+      if (documents.length > 1) {
+        const documentIDsAsBase64Strings = documents.map((document) => document.id.toBase64String())
+        throw new Error(`Internal inconsistency, single document live query returned more than one document. Query: ${this.query}, documentIDs: ${documentIDsAsBase64Strings.join(', ')}.`)
+      }
+
+      if (event.isInitial === false && event.oldDocuments.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one old documents. Query ${this.query}.`)
+      if (event.isInitial === false && event.insertions.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one insertion, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.deletions.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one deletion, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.updates.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one update, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.moves.length > 0) throw new Error(`Internal inconsistency, single document live query returned an update event with moves, which doesn't make sense for single document observations. Query ${this.query}.`)
+
+      const totalNumberOfManipulations = event.isInitial === true ? 0 : event.insertions.length + event.deletions.length + event.updates.length
+      if (totalNumberOfManipulations > 1) throw new Error(`Internal inconsistency, single document live query returned a combination of inserts, updates, and/or deletes, which doesn't make sense for single document observation. Query ${this.query}.`)
+
+
+      const document = documents[0] || null
+      const oldDocument = event.isInitial === true ? undefined : event.oldDocuments[0]
+
+      const singleDocumentEvent = new SingleDocumentLiveQueryEvent(event.isInitial, oldDocument)
+      if (waitForNextSignal) {
+        handler(document, singleDocumentEvent, signalNext)
+      } else {
+        try {
+          handler(document, singleDocumentEvent)
+        } finally {
+          signalNext()
+        }
+      }
+    })
+
+    this.collection.store.ditto.liveQueryManager.startLiveQuery(liveQuery)
+    return liveQuery
+  }
+}

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

@@ -0,0 +1,160 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+import { generateEphemeralToken } from './internal'
+
+import type { Ditto, RemotePeer } from './ditto'
+
+/** @internal */
+export type PresenceToken = string
+
+/**
+ * @internal
+ * @deprecated Replaced by `Presence`.
+ */
+export class PresenceManager {
+  readonly ditto: Ditto
+
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+    this.isClosed = false
+    this.isRegistered = false
+    this.currentRemotePeers = []
+    this.callbacksByPresenceToken = {}
+  }
+
+  /** @internal */
+  addObserver(callback: (remotePeers: RemotePeer[]) => void): PresenceToken {
+    if (this.isClosed) {
+
+      throw new Error(`Internal inconsistency, can't add presence observer, observer mananger close()-ed.`)
+    }
+
+    this.registerIfNeeded()
+
+    const token = generateEphemeralToken()
+    this.callbacksByPresenceToken[token] = callback
+    this.ditto.keepAlive.retain(`PresenceObservation.${token}`)
+
+
+    callback(this.currentRemotePeers)
+
+    return token
+  }
+
+  /** @internal */
+  removeObserver(token: PresenceToken) {
+    const callback = this.callbacksByPresenceToken[token]
+
+    if (typeof callback === 'undefined') {
+      throw new Error(`Can't remove presence observer, token '${token}' has never been registered before.`)
+    }
+
+    if (callback === null) {
+      // Observer has already been removed, no-op.
+      return
+    }
+
+    if (typeof this.callbacksByPresenceToken[token] != 'undefined') {
+      this.ditto.keepAlive.release(`PresenceObservation.${token}`)
+
+      this.callbacksByPresenceToken[token] = null
+      this.unregisterIfNeeded()
+    }
+  }
+
+  /** @internal */
+  hasObserver(token: PresenceToken): boolean {
+    return typeof this.callbacksByPresenceToken[token] != 'undefined'
+  }
+
+  /** @internal */
+  close() {
+    this.isClosed = true
+    for (const token in this.callbacksByPresenceToken) {
+      this.removeObserver(token)
+    }
+  }
+
+  // ------------------------------------------------------------ Private ------
+
+  private isClosed: boolean
+  private isRegistered: boolean
+  private currentRemotePeers: RemotePeer[]
+  private callbacksByPresenceToken: { [key: string]: ((remotePeers: RemotePeer[]) => void) | null }
+
+  private hasObservers(): boolean {
+    return Object.keys(this.callbacksByPresenceToken).length > 0
+  }
+
+  private registerIfNeeded() {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    ditto.deferClose(() => {
+      const needsToRegister = !this.isRegistered
+      if (needsToRegister) {
+        this.isRegistered = true
+        const remotePeersJSONString = FFI.dittoPresenceV1(dittoHandle.deref())
+        this.currentRemotePeers = this.decode(remotePeersJSONString).sort(this.compareRemotePeers)
+        FFI.dittoRegisterPresenceV1Callback(dittoHandle.deref(), this.handlePresenceV1Callback.bind(this))
+      }
+    })
+  }
+
+  private unregisterIfNeeded() {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    ditto.deferClose(() => {
+      const needsToUnregister = !this.hasObservers() && this.isRegistered
+      if (needsToUnregister) {
+        this.isRegistered = false
+        FFI.dittoClearPresenceCallback(dittoHandle.deref())
+        this.currentRemotePeers = []
+      }
+    })
+  }
+
+  private handlePresenceV1Callback(remotePeersJSONString: string) {
+    const remotePeers = this.decode(remotePeersJSONString).sort(this.compareRemotePeers)
+    this.currentRemotePeers = remotePeers
+    this.notify()
+  }
+
+  private notify() {
+    if (this.isClosed) {
+      return
+    }
+
+    for (const token in this.callbacksByPresenceToken) {
+      const callback = this.callbacksByPresenceToken[token]
+      if (callback) callback(this.currentRemotePeers)
+    }
+  }
+
+  private decode(remotePeersJSONString: string): RemotePeer[] {
+    const remotePeersJSON: any[] = JSON.parse(remotePeersJSONString)
+    return remotePeersJSON.map((remotePeerJSON) => {
+      return {
+        networkID: remotePeerJSON['network_id'],
+        deviceName: remotePeerJSON['device_name'],
+        rssi: remotePeerJSON['rssi'] ?? undefined,
+        approximateDistanceInMeters: remotePeerJSON['approximate_distance_in_meters'] ?? undefined,
+        connections: remotePeerJSON['connections'],
+      }
+    })
+  }
+
+  private compareRemotePeers(left: RemotePeer, right: RemotePeer) {
+
+    if (left.connections.length === 0 && right.connections.length > 0) return +1
+    if (left.connections.length > 0 && right.connections.length === 0) return -1
+
+    if (left.deviceName < right.deviceName) return -1
+    if (left.deviceName > right.deviceName) return +1
+
+    return 0
+  }
+}

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

@@ -0,0 +1,238 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+import { Observer } from './observer'
+import { ObserverManager } from './observer-manager'
+import type { Ditto } from './ditto'
+
+/** Types of connections that can be established between two peers. */
+export type ConnectionType = 'P2PWiFi' | 'WebSocket' | 'AccessPoint' | 'Bluetooth'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * An opaque address uniquely identifying another peer on the Ditto mesh
+ * network.
+ *
+ * IMPORTANT: You should not rely on the individual components of the address,
+ * those can change at any time. Please use
+ * {@link addressToString | addressToString()} to compare individual addresses
+ * with each other.
+ */
+export type Address = {
+  siteId: number | BigInt
+  pubkey: Uint8Array
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Returns a string representation of the given address. Use this function
+ * to compare multiple addresses or whenever you need the address to be a key
+ * in a hash object.
+ */
+export function addressToString(address: Address) {
+  return `${address.siteId}-${address.pubkey}`
+}
+
+// -----------------------------------------------------------------------------
+
+/** Represents a connection between two peers on the Ditto mesh network. */
+export type Connection = {
+  /** Unique identifier for the connection.
+   *
+   * These IDs are stable for any two peer keys and a given connection type.
+   *
+   * **Example ID**
+   *
+   * "1<->2:Bluetooth"
+   */
+  id: string
+
+  /** Type of transport enabling this connection. */
+  connectionType: ConnectionType
+
+  /**
+   * Peer key of the peer at one end of the connection.
+   *
+   * This peer key is lexicographically smaller than `peer2`.
+   */
+  peer1: Uint8Array
+
+  /**
+   * Peer key of the peer at the other end of the connection.
+   *
+   * This peer key is lexicographically larger than `peer1`.
+   */
+  peer2: Uint8Array
+
+  /*
+   * Gets an estimate of distance to the remote peer. This value is inaccurate.
+   * The environment, hardware, and several other factors can greatly affect
+   * this value. It is currently derived from RSSI. Can be (yet) unknown and
+   * therefore not set.
+   */
+  approximateDistanceInMeters?: number
+}
+
+// -----------------------------------------------------------------------------
+
+/** An instance of Ditto taking part in the Ditto mesh network. */
+export type Peer = {
+  /**
+   * Address to contact this peer via Ditto Bus, unique with a Ditto mesh
+   * network.
+   */
+  address: Address
+
+  /**
+   * The peer key is a unique identifier for a given peer, equal to or derived
+   * from the cryptographic public key used to authenticate it.
+   *
+   * NOTE: This will be be empty when a peer is not updated to the latest
+   * version of the SDK.
+   */
+  peerKey: Uint8Array
+
+  /**
+   * The human-readable device name of the peer. This defaults to the hostname
+   * but can be manually set by the application developer of the other peer.
+   * It is not necessarily unique.
+   */
+  deviceName: string
+
+  /**
+   * Currently active connections of the peer.
+   */
+  connections: Connection[]
+
+  /**
+   * Indicates whether the peer is connected to Ditto Cloud.
+   */
+  isConnectedToDittoCloud: boolean
+
+  /** The operating system the peer is running on, `undefined` if (yet) unknown. */
+  os?: string
+
+  /** The Ditto SDK version the peer is running with, `undefined` if (yet) unknown. */
+  dittoSDKVersion?: string
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Represents the Ditto mesh network of peers and their connections between each
+ * other. The `localPeer` is the entry point, all others are remote peers known
+ * by the local peer (either directly or via other remote peers).
+ */
+export type PresenceGraph = {
+  /**
+   * Returns the local peer (usually the peer that is represented by the
+   * currently running Ditto instance). The `localPeer` is the entry point, all
+   * others are remote peers known by the local peer (either directly or via
+   * other remote peers).
+   */
+  localPeer: Peer
+
+  /**
+   * Returns all remote peers known by the `localPeer`, either directly or via
+   * other remote peers.
+   */
+  remotePeers: Peer[]
+
+  /**
+   * Returns the underlying CBOR data if the presence graph has been initialized
+   * with CBOR. All of Ditto API returning a presence graph has this property
+   * set.
+   */
+  underlyingCBOR?: Uint8Array
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * The entrypoint for all actions that relate presence of other peers known by
+ * the current peer, either directly or through other peers.
+ *
+ * You don't create one directly but can access it from a particular `Ditto`
+ * instance via its `presence` property.
+ */
+export class Presence {
+  /** The Ditto instance this object belongs to. */
+  readonly ditto: Ditto
+
+  /**
+   * Returns the current presence graph capturing all known peers and
+   * connections between them.
+   */
+  get graph(): PresenceGraph {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferClose(() => {
+      const graphJSONString = FFI.dittoPresenceV3(dittoHandle.deref())
+      return JSON.parse(graphJSONString)
+    })
+  }
+
+  /**
+   * Request information about Ditto peers in range of this device.
+   *
+   * This method returns an observer which should be held as long as updates are
+   * required. A newly registered observer will have a peers update delivered to
+   * it immediately. From then on it will be invoked repeatedly when Ditto
+   * devices come and go, or the active connections to them change.
+   */
+  observe(didChangeHandler: (presenceGraph: PresenceGraph) => void): Observer {
+    const observerToken = this.observerManager.addObserver(didChangeHandler)
+    const observer = new Observer(this.observerManager, observerToken, { stopsWhenFinalized: true })
+
+    // REFACTOR: make the initial callback call async, too (othewise we'd be
+    // mixing sync with async, which is a bit problematic in general but might
+    // be OK with single-threaded JS). This is a bit tricky, simply
+    // setTimeout(..., 0) here could lead us to a situation where the initial
+    // call would be sent AFTER the regular notification.
+    didChangeHandler(this.graph)
+
+    return observer
+  }
+
+  /** @internal */
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+
+    this.observerManager = new ObserverManager('PresenceObservation', {
+      keepAlive: ditto.keepAlive,
+
+      register: (callback) => {
+        const ditto = this.ditto
+        const dittoHandle = Bridge.ditto.handleFor(ditto)
+        ditto.deferClose(() => {
+          FFI.dittoRegisterPresenceV3Callback(dittoHandle.deref(), callback)
+        })
+      },
+
+      unregister: () => {
+        const ditto = this.ditto
+        const dittoHandle = Bridge.ditto.handleFor(ditto)
+        ditto.deferClose(() => {
+          FFI.dittoClearPresenceV3Callback(dittoHandle.deref())
+        })
+      },
+
+      process: (presenceGraphJSONString) => {
+        const presenceGraph = JSON.parse(presenceGraphJSONString)
+        return [presenceGraph]
+      },
+    })
+  }
+
+  /** @internal */
+  close() {
+    this.observerManager.close()
+  }
+
+  private observerManager: ObserverManager
+}