putDocument method

Future<DocumentPutResponse?> putDocument({ required String path, required Uint8List content, String contentType = 'application/json', String? ifMatch, DocumentVisibility? visibility, int? history, PeerId? toServer, })

Put a document to your own store

path Document path (e.g., "profile", "avatar") content Document content bytes contentType MIME content type ifMatch Optional ETag for optimistic locking visibility Optional: who may read it. A new document without one is private to its owner; an existing one keeps its setting. history Optional: how many earlier versions the document keeps, starting with the one this write replaces (the server clamps it to its ceiling). 0 turns history off and deletes the kept versions; null leaves the setting as it is. toServer Optional: specify which server to store to

Implementation

Future<DocumentPutResponse?> putDocument({
  required String path,
  required Uint8List content,
  String contentType = 'application/json',
  String? ifMatch,
  DocumentVisibility? visibility,
  int? history,
  PeerId? toServer,
}) async {
  final serverId = toServer ?? await _serverSelector.selectServer(config.preferredServers);
  if (serverId == null) {
    _logger.warning('No S&F server available for document storage');
    return null;
  }

  try {
    final context = Context();
    final stream = await host.newStream(
      serverId,
      ['/ricochet/store/doc/1.0.0'],
      context,
    ).timeout(config.connectionTimeout);

    final response = await DocumentHandler.putDocument(
      stream,
      ownerPeerId: host.id,  // Can only PUT to own documents
      path: path,
      content: content,
      contentType: contentType,
      ifMatch: ifMatch,
      visibility: visibility,
      history: history,
    ).timeout(config.messageTimeout);

    await stream.close();

    final created = response.status == 201;
    _logger.info('PUT document ${host.id.toBase58().substring(0, 12)}.../doc/$path: ${response.status} ${created ? "Created" : "Updated"}');

    return DocumentPutResponse(
      status: response.status,
      etag: response.etag,
      lastModified: response.lastModified,
      created: created,
    );
  } on TimeoutException {
    _logger.warning('PUT document timed out');
    return null;
  } catch (e) {
    _logger.warning('Failed to PUT document: $e');
    return null;
  }
}