@dittolive/ditto 4.7.4 → 4.8.0-rc.2

package/react-native/src/sources/attachment-fetcher-manager.ts

@@ -1,145 +0,0 @@
-//
-// Copyright © 2023 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-
-import { AttachmentFetcher } from './attachment-fetcher'
-import { AttachmentToken } from './attachment-token'
-import { Bridge } from './bridge'
-
-import type { AttachmentFetchEvent } from './attachment-fetch-event'
-import type { Ditto } from './ditto'
-
-/** @internal */
-type AttachmentFetcherContextInfo = {
-  attachmentFetcher: WeakRef<AttachmentFetcher>
-  // Attachment token is unique per attachment.
-  attachmentTokenID: Uint8Array
-  // This id is unique per attachment fetcher.
-  id: string
-  // Promise for a token that can be used to cancel the fetch. If `null`, the
-  // fetch has already completed, errored, or been canceled.
-  cancelTokenPromise: Promise<number | BigInt | null> | null
-}
-
-/**
- * Manages attachment fetchers to make sure we free all resources when the
- * fetcher is garbage collected and to allow us to wait for freeing of
- * ressources to be finished before the ditto instance is closed.
- *
- * @internal
- */
-export class AttachmentFetcherManager {
-  readonly ditto: Ditto
-
-  /** @internal */
-  constructor(ditto: Ditto) {
-    this.ditto = ditto
-  }
-
-  /**
-   * Start an attachment fetcher.
-   *
-   * @internal */
-  startAttachmentFetcher(token: AttachmentToken, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void): AttachmentFetcher {
-    return this.ditto.deferClose(() => {
-      const attachmentFetcher = new AttachmentFetcher(this.ditto, token, this, eventHandler)
-
-      // Register in finalization registry.
-      const contextInfo: AttachmentFetcherContextInfo = {
-        id: attachmentFetcher.id,
-        attachmentTokenID: token.idBytes,
-        cancelTokenPromise: attachmentFetcher.cancelTokenPromise,
-        attachmentFetcher: new WeakRef(attachmentFetcher),
-      }
-      this.finalizationRegistry.register(attachmentFetcher, contextInfo, attachmentFetcher)
-
-      // Keep a reference to the context info so that we can stop the fetcher.
-      this.contextInfoByID[attachmentFetcher.id] = contextInfo
-
-      // Prevent cancellation of the fetch once it was fulfilled or rejected.
-      const resetCancelToken = () => {
-        if (this.contextInfoByID[attachmentFetcher.id] != null) {
-          this.contextInfoByID[attachmentFetcher.id].cancelTokenPromise = null
-        }
-      }
-      attachmentFetcher.attachment.then(
-        (value) => {
-          resetCancelToken()
-          return value
-        },
-        (reason) => {
-          resetCancelToken()
-          return reason
-        },
-      )
-
-      // Keep the attachment fetcher alive until it is stopped.
-      this.ditto.keepAlive.retain(`AttachmentFetcher.${attachmentFetcher.id})`)
-
-      return attachmentFetcher
-    })
-  }
-
-  /**
-   * Stop an attachment fetcher and wait for it to be stopped.
-   *
-   * @internal */
-  async stopAttachmentFetcher(attachmentFetcher: AttachmentFetcher): Promise<void> {
-    this.finalizationRegistry.unregister(attachmentFetcher)
-    const contextInfo = this.contextInfoByID[attachmentFetcher.id]
-    if (contextInfo == null) {
-      throw new Error(`Internal inconsistency: cannot stop attachment fetcher ${attachmentFetcher.id}, which is not registered.`)
-    }
-    await this.stopWithContextInfo(contextInfo)
-  }
-
-  /**
-   * Closing the manager will cancel all attachment fetchers.
-   *
-   * @internal
-   */
-  close() {
-    void this.ditto.deferCloseAsync(async () => {
-      const contextInfos = Object.values(this.contextInfoByID)
-      const stopped = contextInfos.map(async (contextInfo) => {
-        const attachmentFetcher = contextInfo.attachmentFetcher.deref()
-        if (attachmentFetcher != null) {
-          await this.stopAttachmentFetcher(attachmentFetcher)
-        }
-      })
-      await Promise.all(stopped)
-    })
-  }
-
-  // --- Private ---
-
-  private contextInfoByID: { [attachmentFetcherID: string]: AttachmentFetcherContextInfo } = {}
-
-  private finalizationRegistry: FinalizationRegistry<AttachmentFetcherContextInfo> = new FinalizationRegistry(this.stopWithContextInfo)
-
-  /**
-   * Stop the attachment fetcher without unregistering it from the finalization
-   * registry.
-   */
-  private stopWithContextInfo(contextInfo: AttachmentFetcherContextInfo): Promise<void> {
-    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
-    return this.ditto.deferCloseAsync(async () => {
-      // Remove the manager's own record of the context info.
-      if (this.contextInfoByID[contextInfo.id] == null) {
-        throw new Error(`Internal inconsistency: attachment fetcher ${contextInfo.id} not found in active attachment fetchers.`)
-      }
-      delete this.contextInfoByID[contextInfo.id]
-
-      // Release the keep-alive.
-      this.ditto.keepAlive.release(`AttachmentFetcher.${contextInfo.id})`)
-
-      // Cancel the fetcher if it is still running.
-      const cancelToken = await contextInfo.cancelTokenPromise
-      if (cancelToken) {
-        FFI.dittoCancelResolveAttachment(dittoHandle.deref(), contextInfo.attachmentTokenID, cancelToken)
-      }
-    })
-  }
-}

package/react-native/src/sources/attachment-fetcher.ts

@@ -1,265 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { Bridge } from './bridge'
-import { Attachment } from './attachment'
-import { AttachmentToken } from './attachment-token'
-import { DittoError, mapFFIErrorsAsync } from './error'
-import { generateEphemeralToken, step } from './internal'
-import { Logger } from './logger'
-
-import type { AttachmentFetchEvent } from './attachment-fetch-event'
-import type { Ditto } from './ditto'
-import type { AttachmentFetcherManager } from './attachment-fetcher-manager'
-import type { Store } from './store'
-import type { Collection } from './collection'
-
-/**
- * These objects are returned by calls to
- * {@link Store.fetchAttachment | ditto.store.fetchAttachment()}
- * and allow you to stop an in-flight attachment fetch.
- */
-export class AttachmentFetcher implements PromiseLike<Attachment | null> {
-  /**
-   * Returns a promise for the attachment that you can `await`.
-   *
-   * The promise is rejected if an error occurs during the fetch. Note that the
-   * `AttachmentFetcher` itself implements `PromiseLike`, so you can `await` it
-   * directly.
-   *
-   * If this attachment fetcher has been initiated through {@link
-   * Collection.fetchAttachment | `Collection.fetchAttachment()`}, the promise
-   * resolves to `null` if the attachment could not be found instead of being
-   * rejected.
-   */
-  readonly attachment: Promise<Attachment | null>
-
-  /**
-   * Stops fetching the associated attachment and cleans up any associated
-   * resources.
-   *
-   * Note that you are not required to call `stop()` once your attachment fetch
-   * operation has finished. The method primarily exists to allow you to cancel
-   * an attachment fetch request while it is ongoing if you no longer wish for
-   * the attachment to be made available locally to the device.
-   */
-  stop() {
-    // No need for synchronicity here: we let the "stop promise" float / run in
-    // a detached fashion since there is no point in awaiting the "stop
-    // signaling" itself.
-
-    if (this.manager == null) {
-      // Case where the fetcher was started from `Store.fetchAttachment()`.
-      if (!this.isStopped) {
-        this.rejectPendingFetch()
-        this.rejectPendingFetch = null
-      }
-
-      this.ditto.store.removeAttachmentFetcher(this)
-
-      const dittoHandle = Bridge.ditto.handleFor(this.ditto)
-      void this.ditto.deferCloseAsync(async () => {
-        // Cancel the fetcher if it is still running.
-        const cancelToken = await this.cancelTokenPromise
-        if (cancelToken) {
-          FFI.dittoCancelResolveAttachment(dittoHandle.deref(), this.token.idBytes, cancelToken)
-        }
-      })
-    } else {
-      // Legacy case where the fetcher was started from `Collection.fetchAttachment()`.
-
-      void step(async () => {
-        await this.manager.stopAttachmentFetcher(this)
-        if (this.rejectPendingFetch != null) {
-          this.rejectPendingFetch()
-          this.rejectPendingFetch = null
-        }
-      })
-    }
-  }
-
-  // --------------------------------------- Internal ------------------------
-
-  /** @internal */
-  readonly cancelTokenPromise: Promise<number | BigInt | null> | null = null
-
-  /** @internal */
-  readonly ditto: Ditto
-
-  /** @internal */
-  readonly id: string
-
-  /**
-   * Defined when the fetcher was started from `Collection.fetchAttachment()`.
-   * Otherwise, the fetcher was started from `Store.fetchAttachment()`.
-   *
-   * @internal
-   */
-  readonly manager?: AttachmentFetcherManager
-
-  /** @internal */
-  readonly token: AttachmentToken
-
-  /** @internal */
-  then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2> {
-    return this.attachment.then(onfulfilled, onrejected)
-  }
-
-  /** @internal */
-  constructor(ditto: Ditto, token: AttachmentToken, manager?: AttachmentFetcherManager, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void) {
-    this.ditto = ditto
-    this.token = token
-    this.manager = manager
-    this.id = generateEphemeralToken()
-
-    const eventHandlerOrNoOp = eventHandler || function () {}
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-
-    this.attachment = new Promise((resolve, reject) => {
-      // REFACTOR: The callbacks hold quite a bunch of objects with most
-      // probably lead to retain cycles and therefore memory leaks. This needs
-      // to be
-      // fixed.
-      const onComplete = (attachmentHandlePointer: FFI.Pointer<FFI.AttachmentHandle>) => {
-        const attachment = new Attachment(this.ditto, this.token)
-        Bridge.attachment.bridge(attachmentHandlePointer, () => attachment)
-
-        eventHandlerOrNoOp({ type: 'Completed', attachment })
-
-        this.rejectPendingFetch = null
-        resolve(attachment)
-      }
-
-      const onProgress = (downloaded: number | BigInt, toDownload: number | BigInt) => {
-        eventHandlerOrNoOp({ type: 'Progress', totalBytes: toDownload, downloadedBytes: downloaded })
-      }
-
-      const onDelete = () => {
-        eventHandlerOrNoOp({ type: 'Deleted' })
-
-        if (this.manager != null) {
-          // Legacy behavior: when the attachment is deleted while being fetched
-          // the fetcher is stopped and the promise is resolved to `null`.
-          this.rejectPendingFetch = null
-          resolve(null)
-        } else {
-          this.rejectPendingFetch = null
-          reject(new DittoError('store/attachment-not-found', 'The attachment was deleted while being fetched.'))
-        }
-      }
-
-      const onError = () => {
-        ;(err: any) => {
-          this.rejectPendingFetch = null
-          reject(err)
-        }
-      }
-
-      // The core doesn't call any of the handlers defined above when a fetch is
-      // cancelled through `this.stop()` so we use this function to reject the
-      // promise from the outside.
-      this.rejectPendingFetch = () => {
-        const err = this.manager != null ? new Error('Attachment fetch was canceled') : new DittoError('store/failed-to-fetch-attachment', 'Attachment fetch was canceled')
-        reject(err)
-      }
-
-      // `cancelTokenPromise` resolves once the fetcher has been initialised in
-      // core. This constructor is sync and thus can't await the promise. That
-      // only happens when the cancel token is used, either in `stop()` (for
-      // fetchers started from `Store.fetchAttachment()`) or in
-      // `AttachmentFetcherManager.stopWithContextInfo()` (for fetchers started
-      // from `Collection.fetchAttachment()`).
-      //
-      // In addition, we want to be able to intercept errors that occur after
-      // this constructor has returned. For that, the whole creation of the
-      // cancel token is wrapped in an inline async function that catches any
-      // errors and then doesn't reject the cancel token promise, but the
-      // `attachment` promise and through that the `AttachmentFetcher` itself.
-      const weakThis = new WeakRef(this)
-
-      // @ts-expect-error setting readonly property
-      this.cancelTokenPromise = (async () => {
-        try {
-          return await mapFFIErrorsAsync(async () => FFI.dittoResolveAttachment(dittoHandle.deref(), token.idBytes, { onComplete, onProgress, onDelete }, onError), {
-            1: ['store/failed-to-fetch-attachment', 'Failed to fetch the attachment.'],
-            2: ['store/attachment-token-invalid', 'The attachment token was invalid.'],
-            3: ['store/attachment-not-found', 'The attachment was not found.'],
-          })
-        } catch (e) {
-          let isDeleted = false
-
-          // Legacy behavior: when the attachment is deleted before the fetch is
-          // started, the fetcher is stopped and the promise is resolved to
-          // `null`.
-          if (e instanceof DittoError && e.code === 'store/attachment-not-found') {
-            isDeleted = true
-            eventHandlerOrNoOp({ type: 'Deleted' })
-          }
-
-          Logger.error(e.message)
-
-          const strongThis = weakThis.deref()
-          if (strongThis == null) {
-            // The fetcher was already gc'd, so it's not possible to reject the
-            // `attachment` promise anymore. We stop here as the error has been
-            // logged.
-            return null
-          }
-
-          // When this is called from legacy `Collection.fetchAttachment()`, we
-          // convert the DittoError to a regular Error.
-          if (strongThis.manager != null && e instanceof DittoError) {
-            e = new Error(e.message)
-          }
-
-          strongThis.rejectPendingFetch = null
-
-          // Reject the `attachment` promise to signal that the fetch has
-          // failed, unless this is a legacy fetcher and the attachment was
-          // deleted.
-          if (strongThis.manager != null && isDeleted) {
-            resolve(null)
-          } else {
-            reject(e)
-          }
-
-          // Set cancelTokenPromise to null to indicate that there is nothing to
-          // cancel anymore.
-          return null
-        }
-      })()
-    })
-
-    if (manager == null) {
-      // Remove the attachment fetcher once it is done.
-      this.attachment
-        .then(() => {
-          this.rejectPendingFetch = null
-          this.ditto.store.removeAttachmentFetcher(this)
-        })
-        .catch(() => {
-          this.rejectPendingFetch = null
-          this.ditto.store.removeAttachmentFetcher(this)
-        })
-    }
-  }
-
-  /**
-   * `true` if the fetcher has completed or was stopped.
-   *
-   * @internal
-   */
-  get isStopped(): boolean {
-    return this.rejectPendingFetch == null
-  }
-
-  /**
-   * This function is defined while a fetch is in progress and is used to reject
-   * the promise `this.attachment` when the fetch is canceled.
-   *
-   * @internal
-   */
-  private rejectPendingFetch: (() => void) | null = null
-}

package/react-native/src/sources/attachment-token.ts

@@ -1,129 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { mapFFIErrors } from './error'
-
-import type { AttachmentMetadata } from './attachment'
-import type { Store } from './store'
-
-/** @internal */
-export type UntypedAttachmentToken = { id: string; len: number | BigInt; metadata: AttachmentMetadata }
-
-/** @internal */
-export type TypedAttachmentToken = { [FFI.DittoCRDTTypeKey]?: FFI.DittoCRDTType.attachment; _id: Uint8Array; _len: number | BigInt; _meta: AttachmentMetadata }
-
-/**
- * Serves as a token for a specific attachment that you can pass to a call to
- * {@link Store.fetchAttachment | ditto.store.fetchAttachment()}.
- */
-export class AttachmentToken {
-  /** The attachment's ID. */
-  // This ID is a _non-padded_ base64-encoded version of `idBytes`.
-  readonly id: string
-
-  /** The attachment's size given as number of bytes. */
-  readonly len: number | BigInt
-
-  /** The attachment's metadata. */
-  readonly metadata: AttachmentMetadata
-
-  // -------------------------------------------------------------------------
-
-  /** @internal */
-  constructor(jsObj: UntypedAttachmentToken | TypedAttachmentToken) {
-    // There are two representations of attachment tokens:
-    // 1. The legacy typed representation is an internal format that is used by
-    //    the query builder API. It can be identified by the presence of the
-    //    [FFI.DittoCRDTTypeKey] field.
-    // 2. The untyped representation is used in our public API and was first
-    //    introduced in the HTTP API. It is now used by the DQL API as well. It
-    //    uses a non-padded base64-encoded ID.
-    let id: Uint8Array, len: number | BigInt, meta: AttachmentMetadata
-    if (jsObj[FFI.DittoCRDTTypeKey] != null) {
-      ;({ id, len, meta } = AttachmentToken.validateTypedInput(jsObj as TypedAttachmentToken))
-    } else {
-      ;({ id, len, meta } = AttachmentToken.validateUntypedInput(jsObj as UntypedAttachmentToken))
-    }
-
-    // base64-encode string and remove padding
-    this.id = mapFFIErrors(() => FFI.base64encode(id, 'Unpadded'))
-    this.idBytes = id
-    this.len = len
-    this.metadata = meta
-  }
-
-  /** @internal */
-  readonly idBytes: Uint8Array
-
-  /**
-   * Validate an input value that has a field `[FFI.DittoCRDTTypeKey]` and
-   * return its contents.
-   *
-   * @throws {Error} If the input is invalid.
-   * @returns {object} binary id, len and metadata of the attachment token
-   */
-  private static validateTypedInput(jsObj: TypedAttachmentToken): { id: Uint8Array; len: number | BigInt; meta: AttachmentMetadata } {
-    const type = jsObj[FFI.DittoCRDTTypeKey]
-    if (type !== FFI.DittoCRDTType.attachment) {
-      throw new Error('Invalid attachment token')
-    }
-
-    const id = jsObj['_id']
-    if (!(id instanceof Uint8Array)) {
-      throw new Error('Invalid attachment token id')
-    }
-
-    const len = jsObj['_len']
-    if ((typeof len !== 'number' && typeof len !== 'bigint') || len < 0) {
-      throw new Error('Invalid attachment token length, must be a non-negative number or bigint')
-    }
-
-    const meta = jsObj['_meta']
-    if (typeof meta !== 'object') {
-      throw new Error('Invalid attachment token meta')
-    }
-
-    return { id, len, meta }
-  }
-
-  /**
-   * Validate an untyped input value and return its contents.
-   *
-   * Converts _unpadded_ base64-encoded ID in input to _padded_ base64-encoded
-   * ID before returning it as `Uint8Array`.
-   *
-   * @throws {@link DittoError} `store/attachment-token-invalid` If the input id
-   * is not a valid base64 string.
-   * @returns {object} binary id, len and metadata of the attachment token
-   */
-  private static validateUntypedInput(jsObj: UntypedAttachmentToken): { id: Uint8Array; len: number | BigInt; meta: AttachmentMetadata } {
-    const idBase64 = jsObj['id']
-    if (typeof idBase64 !== 'string') {
-      throw new Error('Invalid attachment token id')
-    }
-
-    const id = mapFFIErrors(
-      () => FFI.tryBase64Decode(idBase64, 'Unpadded'),
-      {
-        Base64Invalid: ['store/attachment-token-invalid', 'Failed to decode attachment token id from base64 input'],
-      },
-      {
-        attachmentTokenID: idBase64,
-      },
-    )
-
-    const len = jsObj['len']
-    if ((typeof len !== 'number' && typeof len !== 'bigint') || len < 0) {
-      throw new Error('Invalid attachment token length, must be a non-negative number or bigint')
-    }
-
-    const meta = jsObj['metadata']
-    if (typeof meta !== 'object') {
-      throw new Error('Invalid attachment token meta')
-    }
-
-    return { id, len, meta }
-  }
-}

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

@@ -1,121 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import * as Environment from './@environment'
-import { Bridge } from './bridge'
-import { DittoError } from './error'
-
-import type { Ditto } from './ditto'
-import type { AttachmentToken } from './attachment-token'
-
-/**
- * A key-value map of user-defined metadata for an attachment.
- */
-export type AttachmentMetadata = { [key: string]: string }
-
-/**
- * Represents an attachment and can be used to insert the associated attachment
- * into a document at a specific key-path. You can't instantiate an attachment
- * directly, please use the
- * {@link Store.newAttachment | ditto.store.newAttachment()} method instead.
- */
-export class Attachment {
-  /** @internal */
-  readonly ditto: Ditto
-
-  /** @internal */
-  readonly token: AttachmentToken
-
-  /** The attachment's ID. */
-  get id(): string {
-    return this.token.id
-  }
-
-  /** The attachment's size given as number of bytes. */
-  get len(): number | BigInt {
-    return this.token.len
-  }
-
-  /** The attachment's metadata. */
-  get metadata(): { [key: string]: string } {
-    return this.token.metadata
-  }
-
-  /**
-   * Returns the attachment's data.
-   */
-  data(): Promise<Uint8Array> {
-    const ditto = this.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-    return this.ditto.deferCloseAsync(async () => {
-
-
-      if (Environment.isReactNativeBuild) {
-        const attachmentHandle = Bridge.attachment.handleFor(this)
-        const attachmentPath = FFI.dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref())
-        return await FFI.readFile(attachmentPath)
-      }
-    })
-  }
-
-  /**
-   * Returns the attachment's data.
-   *
-   * @deprecated Use `data()` instead.
-   */
-  getData(): Promise<Uint8Array> {
-    return this.data()
-  }
-
-  /**
-   * Copies the attachment to the specified file path. Node-only,
-   * throws in the browser.
-   *
-   * @param path The path that the attachment should be copied to.
-   */
-  copyToPath(path: string): Promise<void> {
-    const ditto = this.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-    return this.ditto.deferCloseAsync(async () => {
-
-      if (Environment.isReactNativeBuild) {
-        const attachmentHandle = Bridge.attachment.handleFor(this)
-        const attachmentPath = FFI.dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref())
-        // If the file already exists, we fail. This is the same behavior as
-        // for the Swift/ObjC SDK.
-        return await FFI.copyFile(attachmentPath, path, ditto.persistenceDirectory)
-      }
-    })
-  }
-
-  /** @internal */
-  constructor(ditto: Ditto, token: AttachmentToken) {
-    this.ditto = ditto
-    this.token = token
-  }
-}
-
-/**
- * Validates the given attachment metadata. Metadata must be a flat object with
- * string values.
- *
- * This should really happen in core to make sure we use the same validation
- * logic across SDKs but we decided to postpone that for the next iteration on
- * attachments.
- *
- * @throws {@link DittoError} 'store/failed-to-create-attachment'
- * @internal
- */
-export function validateAttachmentMetadata(metadata: AttachmentMetadata): void {
-  if (typeof metadata !== 'object') {
-    throw new DittoError('store/failed-to-create-attachment', `Invalid attachment metadata: expected a value of type object but got ${typeof metadata}.`)
-  }
-
-  for (const key in metadata) {
-    if (typeof metadata[key] !== 'string') {
-      throw new DittoError('store/failed-to-create-attachment', `Invalid attachment metadata: metadata values must be strings but key '${key}' has a value of type ${typeof metadata[key]}.`)
-    }
-  }
-}