@dittolive/ditto 4.4.4 → 4.5.0

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

@@ -0,0 +1,163 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import type { AuthenticationHandler } from './authenticator'
+
+/**
+ * An identity to be used while in development when you want to control the app
+ * name and the site ID of the peer.
+ */
+export interface IdentityOfflinePlayground {
+  type: 'offlinePlayground'
+
+  /**
+   * The app ID for the Ditto instance.
+   */
+  appID: string
+
+  /**
+   * The `siteID` needs to be an unsigned 64 bit integer >= 0, i.e. either a
+   * regular non-fractional `number` or a `BigInt` in the range between 0 and
+   * 2^64 - 1 (inclusive). If `siteID` is `0`, Ditto will generate an
+   * appropriate site ID and persist it when needed. Default is `0`.
+   */
+  siteID?: number | BigInt
+}
+
+/**
+ * An identity with intermediate level of security where all users and devices
+ * are trusted and a single shared secret (key) between all peers satisfies the
+ * security requirements.
+ *
+ * **NOTE**: This identity type is only supported for Node environments, using
+ * this to create a Ditto instance in the web browser will throw an exception.
+ */
+export interface IdentitySharedKey {
+  type: 'sharedKey'
+
+  /**
+   * The app ID for the Ditto instance.
+   */
+  appID: string
+
+  /**
+   * The `siteID` needs to be an unsigned 64 bit integer >= 0, i.e. either a
+   * regular non-fractional `number` or a `BigInt` in the range between 0 and
+   * 2^64 - 1 (inclusive). If `siteID` is `0`, Ditto will generate an
+   * appropriate site ID and persist it when needed. Default is `0`.
+   */
+  siteID?: number | BigInt
+
+  /**
+   * A base64 encoded DER representation of a private key, which is shared
+   * between devices for a single app.
+   */
+  sharedKey: string
+}
+
+/**
+ * A manually-provided certificate identity. This accepts a
+ * base64-encoded bundle.
+ *
+ * A manual identity's `appID` is encoded in its certificate.
+ */
+export interface IdentityManual {
+  type: 'manual'
+  certificate: string
+}
+
+/**
+ * Test a Ditto Cloud app with weak shared token authentication ("Playground
+ * mode"). This mode is not secure and must only be used for development.
+ */
+export interface IdentityOnlinePlayground {
+  type: 'onlinePlayground'
+
+  /**
+   * An ID identifying this app registration on the Ditto portal, which can be
+   * found at https://portal.ditto.live.
+   */
+  appID: string
+
+  /**
+   * A shared token used to set up the OnlinePlayground session. This token is
+   * provided by the Ditto Portal when setting up the application.
+   */
+  token: string
+
+  /** If true, auto-configure sync with Ditto Cloud. Default is `true`. */
+  enableDittoCloudSync?: boolean
+
+  /**
+   * If specified, use a custom authentication service instead of Ditto Cloud.
+   * @internal
+   */
+  customAuthURL?: string
+
+  /**
+   * A custom Ditto Cloud URL.
+   * @internal
+   */
+  customDittoCloudURL?: string
+}
+
+/**
+ * Run Ditto in secure production mode, logging on to Ditto Cloud or an
+ * on-premises authentication server. User permissions are centrally managed.
+ * Sync will not work until a successful login has occurred.
+ *
+ * The only required configuration is the application's UUID, which can be found
+ * on the Ditto portal where the app is registered.
+ *
+ * By default cloud sync is enabled. This means the SDK will sync to a Big Peer
+ * in Ditto's cloud when an internet connection is available. This is controlled
+ * by the `enableCloudSync` parameter. If `true` (default), a suitable wss://
+ * URL will be added to the `TransportConfig`. To prevent cloud sync, or to
+ * specify your own URL later, pass `false`.
+ *
+ * Authentication requests are handled by Ditto's cloud by default, configured
+ * in the portal at https://portal.ditto.live.
+ *
+ * To use a different or on-premises authentication service, pass a custom HTTPS
+ * base URL as the `customAuthUrl` parameter.
+ */
+export interface IdentityOnlineWithAuthentication {
+  type: 'onlineWithAuthentication'
+
+  /**
+   * An ID identifying this app registration on the Ditto portal, which can be
+   * found at https://portal.ditto.live.
+   */
+  appID: string
+
+  /**
+   * If true, auto-configure sync with Ditto Cloud. Default is `true`.
+   */
+  enableDittoCloudSync?: boolean
+
+  /**
+   * A handler for when Ditto requires (re)authentication.
+   */
+  authHandler: AuthenticationHandler
+
+  /**
+   * If specified, use a custom authentication service instead of Ditto Cloud.
+   */
+  customAuthURL?: string
+
+  /**
+   * A custom Ditto Cloud URL.
+   * @internal
+   */
+  customDittoCloudURL?: string
+}
+
+/**
+ * The various identity configurations that you can use when initializing a
+ * `Ditto` instance.
+ */
+export type Identity = IdentityOfflinePlayground | IdentitySharedKey | IdentityManual | IdentityOnlinePlayground | IdentityOnlineWithAuthentication
+
+/** The list of identity types that require activation through an offlineLicenseToken */
+export const IdentityTypesRequiringOfflineLicenseToken = ['manual', 'sharedKey', 'offlinePlayground']

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

@@ -0,0 +1,70 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import * as Environment from './@environment'
+
+import { fullBuildVersionString, defaultDittoWasmFileURL } from './build-time-constants'
+import type { WebAssemblyModule } from './ffi'
+
+let isInitialized = false
+
+export { WebAssemblyModule }
+
+/**
+ * Available options for {@link init | init()}.
+ */
+export type InitOptions = {
+  /**
+   * You can explicitly pass the WebAssembly module or its location via the
+   * `webAssemblyModule` option. By default, Ditto tries to load the WebAssembly
+   * module from the same path where this JavaScript is served.
+   */
+  webAssemblyModule?: WebAssemblyModule
+}
+
+/**
+ * Initializes the whole Ditto module. Needs to be called and complete before
+ * any of the Ditto API is used.
+ *
+ * @param options - Dictionary with global {@link InitOptions | initialization options}.
+ */
+export async function init(options: InitOptions = {}): Promise<void> {
+  if (!isInitialized) {
+    if (Environment.isWebBuild) {
+
+
+      const webAssemblyModule = options.webAssemblyModule || defaultDittoWasmFileURL
+
+      await FFI.init(webAssemblyModule)
+
+      FFI.initSDKVersion('Web', 'JavaScript', fullBuildVersionString)
+      FFI.loggerInit()
+    }
+
+    isInitialized = true
+  }
+}
+
+if (Environment.isNodeBuild) {
+  switch (process.platform) {
+    case 'android':
+      FFI.initSDKVersion('Android', 'JavaScript', fullBuildVersionString)
+      break
+    case 'darwin':
+      FFI.initSDKVersion('Mac', 'JavaScript', fullBuildVersionString)
+      break
+    case 'linux':
+      FFI.initSDKVersion('Linux', 'JavaScript', fullBuildVersionString)
+      break
+    case 'win32':
+      FFI.initSDKVersion('Windows', 'JavaScript', fullBuildVersionString)
+      break
+    default:
+      FFI.initSDKVersion('Unknown', 'JavaScript', fullBuildVersionString)
+      break
+  }
+
+  FFI.loggerInit()
+}

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

@@ -0,0 +1,113 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import * as Environment from './@environment'
+
+// ------------------------------------------------------------ Constants ------
+
+export const defaultDittoCloudDomain = `cloud.ditto.live`
+
+// ------------------------------------------------------------- Defaults ------
+
+/** @internal */
+export function defaultAuthURL(appID: string): string {
+  return `https://${appID}.${defaultDittoCloudDomain}`
+}
+
+/** @internal */
+export function defaultDittoCloudURL(appID: string): string {
+  return `wss://${appID}.${defaultDittoCloudDomain}`
+}
+
+// ---------------------------------------------------------- Validations ------
+
+/**
+ * Validates a number and returns it as-is if all requirements are met,
+ * otherwise throws an exception. Options:
+ *
+ * - `integer`: if `true`, requires the number to be an integer
+ *
+ * - `min`: if given, requires the number to be >= `min`
+ * - `max`: if given, requires the number to be <= `max`
+ *
+ * - `minX`: if given, requires the number to be > `minX` (x stands for "exclusive")
+ * - `maxX`: if given, requires the number to be < `maxX` (x stands for "exclusive")
+ *
+ * You can also customize the error message by providing a prefix via
+ * `errorMessagePrefix`, which defaults to `"Number validation failed:"`.
+ *
+ * @internal
+ */
+export function validateNumber(value, options = {}): number {
+  const errorMessagePrefix = options['errorMessagePrefix'] ?? 'Number validation failed:'
+  const integer = !!options['integer']
+
+  const min = options['min']
+  const max = options['max']
+
+  const minX = options['minX']
+  const maxX = options['maxX']
+
+  if (typeof value !== 'number') throw new Error(`${errorMessagePrefix} '${value}' is not a number.`)
+  if (integer && Math.floor(value) !== value) throw new Error(`${errorMessagePrefix} '${value}' is not an integer.`)
+
+  if (typeof min !== 'undefined' && value < min) throw new Error(`${errorMessagePrefix} '${value}' must be >= ${min}.`)
+  if (typeof max !== 'undefined' && value > max) throw new Error(`${errorMessagePrefix} '${value}' must be <= ${max}.`)
+
+  if (typeof minX !== 'undefined' && value <= minX) throw new Error(`${errorMessagePrefix} '${value}' must be > ${minX}.`)
+  if (typeof maxX !== 'undefined' && value >= maxX) throw new Error(`${errorMessagePrefix} '${value}' must be < ${maxX}.`)
+
+  return value
+}
+
+export function validateQuery(query, options = {}): string {
+  const errorMessagePrefix = options['errorMessagePrefix'] ?? 'Query validation failed,'
+
+  if (typeof query !== 'string') throw new Error(`${errorMessagePrefix} query is not a string: ${query}`)
+  if (query === '') throw new Error(`${errorMessagePrefix} query is an empty string.`)
+
+  const validatedQuery = query.trim()
+  if (validatedQuery === '') throw new Error(`${errorMessagePrefix} query contains only whitespace characters.`)
+  return validatedQuery
+}
+
+// -------------------------------------------------------------- Helpers ------
+
+/**
+ * Generate a random hex-encoded token using the WebCrypto API.
+ *
+ * @internal */
+export function generateEphemeralToken(): string {
+  let webcrypto = undefined
+
+  let data = new Uint16Array(16)
+  if (Environment.isReactNativeBuild) {
+    data = FFI.getRandomValues(data) as Uint16Array
+  } else {
+    throw new Error('Internal inconsistency, incorrect environment to run getRandomValues()')
+  }
+
+  const doublets = Array.from(data)
+  return doublets.map((doublet) => doublet.toString(16)).join('')
+}
+
+// --------------------------------------------------------------- System ------
+
+/** @internal */
+export function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    setTimeout(resolve, milliseconds)
+  })
+}
+
+/** @internal use this to asyncify chunks of code. */
+export async function step<T>(closure: () => T): Promise<T> {
+  await sleep(0)
+  return closure()
+}
+
+/** @internal */
+
+export const performAsyncToWorkaroundNonAsyncFFIAPI = step

package/react-native/src/sources/keep-alive.ts

@@ -0,0 +1,69 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+/** @internal */
+export class KeepAlive {
+  /** @internal */
+  get isActive(): boolean {
+    return this.intervalID !== null
+  }
+
+  /** @internal */
+  constructor() {
+    this.countsByID = {}
+    this.intervalID = null
+  }
+
+  /** @internal */
+  retain(id: string): void {
+    if (typeof this.countsByID[id] === 'undefined') {
+      this.countsByID[id] = 0
+    }
+
+    this.countsByID[id] += 1
+
+    if (this.intervalID === null) {
+      const maxDelay = 2147483647
+      this.intervalID = setInterval(() => {
+        /* no-op */
+      }, maxDelay)
+      KeepAlive.finalizationRegistry.register(this, this.intervalID, this)
+    }
+  }
+
+  /** @internal */
+  release(id: string): void {
+    if (typeof this.countsByID[id] === 'undefined') {
+      throw new Error(`Internal inconsistency, trying to release a keep-alive ID that hasn't been retained before or isn't tracked anymore: ${id}`)
+    }
+
+    this.countsByID[id] -= 1
+
+    if (this.countsByID[id] === 0) {
+      delete this.countsByID[id]
+    }
+
+    if (Object.keys(this.countsByID).length === 0) {
+
+      KeepAlive.finalizationRegistry.unregister(this)
+      clearInterval(this.intervalID)
+      this.intervalID = null
+    }
+  }
+
+  /** @internal */
+  currentIDs(): string[] {
+    return Object.keys(this.countsByID)
+  }
+
+  /** @internal */
+  countForID(id: string): number | null {
+    return this.countsByID[id] ?? null
+  }
+
+  private static finalizationRegistry = new FinalizationRegistry(clearInterval)
+
+  private intervalID
+  private countsByID
+}

package/react-native/src/sources/key-path.ts

@@ -0,0 +1,195 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+const regularKeyPattern = /\.([A-Za-z_]\w*)/.source
+const subscriptIndexPattern = /\[(\d+)\]/.source
+const subscriptSingleQuoteKeyPattern = /\[\'(.+?)\'\]/.source
+const subscriptDoubleQuoteKeyPattern = /\[\"(.+?)\"\]/.source
+const validKeyPathPattern = `((${regularKeyPattern})|(${subscriptIndexPattern})|(${subscriptSingleQuoteKeyPattern})|(${subscriptDoubleQuoteKeyPattern}))*`
+
+const regularKeyRegExp = new RegExp(`^${regularKeyPattern}`)
+const subscriptIndexRegExp = new RegExp(`^${subscriptIndexPattern}`)
+const subscriptSingleQuoteKeyRegExp = new RegExp(`^${subscriptSingleQuoteKeyPattern}`)
+const subscriptDoubleQuoteKeyRegExp = new RegExp(`^${subscriptDoubleQuoteKeyPattern}`)
+const validKeyPathRegExp = new RegExp(`^${validKeyPathPattern}$`)
+
+export type KeyPathValidateOptions = {
+  isInitial?: boolean // default: false
+}
+
+export type KeyPathEvaluateOptions = {
+  stopAtLastContainer?: boolean // default: false
+}
+
+export type KeyPathEvaluationResult = {
+  keyPath: string | number
+  object: any
+  options: KeyPathEvaluateOptions
+  coveredPath: string | number
+  nextPathComponent: string | number | null
+  remainingPath: string | number
+  value: any
+}
+
+/**
+ * Namespace for key-path related functions.
+ * @internal
+ */
+export class KeyPath {
+  /**
+   * Returns the key-path by prefixing it with a leading dot if first key
+   * starts with a character or an underscore.
+   */
+  static withLeadingDot(keyPath: string | number): any /* string | number */ {
+    if (typeof keyPath === 'number') {
+      return keyPath
+    }
+
+    if (typeof keyPath !== 'string') {
+      throw new Error(`Key-path must be a string or a number but is ${typeof keyPath}: ${keyPath}`)
+    }
+
+    const needsLeadingDot = typeof keyPath === 'string' && !!keyPath.match(/^[A-Za-z_]/)
+    return needsLeadingDot ? `.${keyPath}` : keyPath
+  }
+
+  /**
+   * Returns the key-path by removing the leading dot if it starts with one.
+   */
+  static withoutLeadingDot(keyPath: string | number): any /* string | number */ {
+    if (typeof keyPath === 'number') {
+      return keyPath
+    }
+
+    if (typeof keyPath !== 'string') {
+      throw new Error(`Key-path must be a string or a number but is ${typeof keyPath}: ${keyPath}`)
+    }
+
+    const hasLeadingDot = typeof keyPath === 'string' && !!keyPath.match(/^\./)
+    return hasLeadingDot ? keyPath.slice(1) : keyPath
+  }
+
+  /**
+   * Validates a key-path by adding a leading dot if appropriate and checking
+   * its syntax. Throws if syntax is invalid.
+   */
+  static validate(keyPath: string | number, options: KeyPathValidateOptions = {}): any /* string | number */ {
+    const isInitial = options.isInitial ?? false
+
+    if (typeof keyPath === 'number') {
+      return Math.floor(Math.abs(keyPath))
+    }
+
+    if (typeof keyPath !== 'string') {
+      throw new Error(`Key-path must be a string or a number but is ${typeof keyPath}: ${keyPath}`)
+    }
+
+    const keyPathWithLeadingDot = this.withLeadingDot(keyPath) as string
+
+    if (!validKeyPathRegExp.test(keyPathWithLeadingDot)) {
+      throw new Error(`Key-path is not valid: ${keyPath}`)
+    }
+
+    return isInitial ? keyPath : keyPathWithLeadingDot
+  }
+
+  /**
+   * Follows the `keyPath`, boring down through `object` recursively until the
+   * final key-path is reached. Implemented as a free function to help ensure it's
+   * purely functional in nature and that no modifications are made to a
+   * `Document{ID}` or `DocumentPath` where similarly named variables are at play.
+   * @internal
+   */
+  static evaluate(keyPath: string | number, object: any, options: KeyPathEvaluateOptions = {}): KeyPathEvaluationResult {
+    const stopAtLastContainer = options.stopAtLastContainer ?? false
+
+    const evaluationResult = {
+      keyPath: keyPath,
+      object: object,
+      options: { ...options },
+      coveredPath: null,
+      nextPathComponent: null,
+      remainingPath: keyPath,
+      value: object,
+    }
+
+    function advance(keyPath: string | number): { nextPathComponentRaw: string | number; nextPathComponent: string | number; remainingPath: string } {
+      if (typeof keyPath === 'number') {
+        return { nextPathComponentRaw: keyPath, nextPathComponent: keyPath, remainingPath: '' }
+      }
+
+      if (typeof keyPath !== 'string') {
+        throw new Error(`Can't return value at given keyPath, expected keyPath to be a string or a number but got ${typeof keyPath}: ${keyPath}`)
+      }
+
+
+
+      const regularKeyMatch = keyPath.match(regularKeyRegExp)
+      if (regularKeyMatch !== null) {
+        const nextPathComponentRaw = regularKeyMatch[0]
+        const nextPathComponent = regularKeyMatch[1]
+        const remainingPath = keyPath.slice(nextPathComponent.length + /* stripped out . */ 1)
+        return { nextPathComponentRaw, nextPathComponent, remainingPath }
+      }
+
+      const subscriptIndexMatch = keyPath.match(subscriptIndexRegExp)
+      if (subscriptIndexMatch !== null) {
+        const nextPathComponentRaw = subscriptIndexMatch[0]
+        const nextPathComponentString = subscriptIndexMatch[1]
+        const nextPathComponent = parseInt(nextPathComponentString)
+        const remainingPath = keyPath.slice(nextPathComponentString.length + /* stripped out [] */ 2)
+        return { nextPathComponentRaw, nextPathComponent, remainingPath }
+      }
+
+      const subscriptSingleQuoteMatch = keyPath.match(subscriptSingleQuoteKeyRegExp)
+      if (subscriptSingleQuoteMatch !== null) {
+        const nextPathComponentRaw = subscriptSingleQuoteMatch[0]
+        const nextPathComponent = subscriptSingleQuoteMatch[1]
+        const remainingPath = keyPath.slice(nextPathComponent.length + /* stripped out [''] */ 4)
+        return { nextPathComponentRaw, nextPathComponent, remainingPath }
+      }
+
+      const subscriptDoubleQuoteMatch = keyPath.match(subscriptDoubleQuoteKeyRegExp)
+      if (subscriptDoubleQuoteMatch !== null) {
+        const nextPathComponentRaw = subscriptDoubleQuoteMatch[0]
+        const nextPathComponent = subscriptDoubleQuoteMatch[1]
+        const remainingPath = keyPath.slice(nextPathComponent.length + /* stripped out [""] */ 4)
+        return { nextPathComponentRaw, nextPathComponent, remainingPath }
+      }
+
+      throw new Error(`Can't return value at keyPath because the following part of the keyPath is invalid: ${keyPath}`)
+    }
+
+    function recurse(object: any, keyPath: string | number): KeyPathEvaluationResult {
+      if (keyPath === '') {
+        evaluationResult.value = object
+        return evaluationResult
+      }
+
+      const { nextPathComponentRaw, nextPathComponent, remainingPath } = advance(keyPath)
+
+      evaluationResult.nextPathComponent = nextPathComponent
+      evaluationResult.remainingPath = remainingPath
+
+      if (evaluationResult.coveredPath === null || typeof nextPathComponentRaw === 'number') {
+        evaluationResult.coveredPath = nextPathComponentRaw
+      } else {
+        evaluationResult.coveredPath += nextPathComponentRaw
+      }
+
+      if (remainingPath === '' && stopAtLastContainer) {
+        evaluationResult.value = object
+        return evaluationResult
+      }
+
+      const nextObject = object[nextPathComponent]
+      return recurse(nextObject, remainingPath)
+    }
+
+    const keyPathWithLeadingDot = this.withLeadingDot(keyPath)
+    return recurse(object, keyPathWithLeadingDot)
+  }
+
+  private constructor() {}
+}