stat method

Future<MFSStat> stat(
  1. String path, {
  2. bool withLocal = false,
  3. String? cidBase,
})

Gets Kubo-compatible information about a file or directory at path.

path may be an MFS path or an /ipfs/<cid>[/sub] path.

cidBase controls the multibase used to encode the returned CID (e.g. base32). withLocal computes how much of the DAG is present locally. Kubo's hash/size flags only affect the CLI text format, so they are accepted by the RPC handler but intentionally ignored here.

Implementation

Future<MFSStat> stat(
  String path, {
  bool withLocal = false,
  String? cidBase,
}) async {
  final cid = await _resolveAny(path);
  if (cid == null) throw Exception('Path not found: $path');

  final block = await _blockStore.getBlock(cid.encode());
  if (!block.found) throw Exception('Block not found for CID: $cid');

  final hashString = cidBase != null
      ? cid.encodeWithBaseName(cidBase)
      : cid.encode();

  // Raw blocks carry no UnixFS wrapper; report them as files whose size is
  // the block payload itself.
  if (cid.codec == 'raw') {
    final dataLength = block.block.data.length;
    bool? local;
    int? sizeLocal;
    if (withLocal) {
      local = true;
      sizeLocal = dataLength;
    }
    return MFSStat(
      hash: hashString,
      size: dataLength,
      cumulativeSize: dataLength,
      blocks: 0,
      type: 'file',
      withLocal: withLocal ? true : null,
      local: local,
      sizeLocal: sizeLocal,
    );
  }

  final node = PBNode.fromBuffer(block.block.data);
  final unixData = Data.fromBuffer(node.data);

  final typeName = _typeName(unixData.type);
  final cumulativeSize = _cumulativeSize(node);
  final fileSize = unixData.filesize.toInt();

  int? mode;
  int? mtime;
  int? mtimeNsecs;
  if (unixData.hasMode()) mode = unixData.mode;
  if (unixData.hasMtime()) mtime = unixData.mtime.toInt();
  if (unixData.hasMtimeNsecs()) mtimeNsecs = unixData.mtimeNsecs;

  bool? local;
  int? sizeLocal;
  if (withLocal) {
    final localStats = await _localStats(cid);
    local = localStats.$1;
    sizeLocal = localStats.$2;
  }

  return MFSStat(
    hash: hashString,
    size: typeName == 'directory' ? 0 : fileSize,
    cumulativeSize: cumulativeSize,
    blocks: node.links.length,
    type: typeName,
    withLocal: withLocal ? true : null,
    local: local,
    sizeLocal: sizeLocal,
    mode: mode,
    mtime: mtime,
    mtimeNsecs: mtimeNsecs,
  );
}