services/network/public/mojom/http_cache_backend_file_operations.mojom

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/file_error.mojom";
import "mojo/public/mojom/base/file_info.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/time.mojom";


// Flags for HttpCacheBackendFileOperations.OpenFile. Flag values must be
// aligned with base::File::Flags.
enum HttpCacheBackendOpenFileFlags {
  kOpenAndRead = 0x21,
  kCreateAndWrite = 0x42,
  kOpenReadWriteWinShareDelete = 0x8061,
  kCreateReadWriteWinShareDelete = 0x8062,
  kCreateAlwaysWriteWinShareDelete = 0x8048,
  kOpenReadWinShareDeleteWinSequentialScan = 0x88021,
};

// An enum representing the mode for DeleteFile function.
enum HttpCacheBackendDeleteFileMode {
  // The "default" mode, meaning base::DeleteFile.
  kDefault,
  // Ensure that new files for the same name can be created immediately after
  // deletion. Note that this is the default behavior on POSIX. On Windows
  // this assumes that all the file handles for the file to be deleted are
  // opened with FLAG_WIN_SHARE_DELETE.
  kEnsureImmediateAvailability,
};

// File information generated by FileEnumerator.
struct FileEnumerationEntry {
  mojo_base.mojom.FilePath path;
  int64 size;
  mojo_base.mojom.Time last_accessed;
  mojo_base.mojom.Time last_modified;
};

// An interface to enumerate files in a directory.
interface FileEnumerator {
  // Returns next `num_entries` files. `end` is true when we reach the end,
  // and `error` is true when we see an error during traversal. Indirect
  // descendants are not listed, and directories are not listed.
  [Sync] GetNext(uint32 num_entries) =>
      (array<FileEnumerationEntry> entries, bool end, bool error);
};

// An interface to provide file operations so that the HTTP cache works in
// a sandboxed network service.
// All the paths must be absolute paths.
interface HttpCacheBackendFileOperations {
  // Creates a directory with the given path and returns whether that succeeded.
  [Sync] CreateDirectory(mojo_base.mojom.FilePath path) => (bool result);

  // Returns true if the given path exists on the local filesystem.
  [Sync] PathExists(mojo_base.mojom.FilePath path) => (bool result);

  // Returns true if the given path exists on the local filesystem and it's a
  // directory.
  [Sync] DirectoryExists(mojo_base.mojom.FilePath path) => (bool result);

  // Opens a file with the given path and flags. Returns the opened file and
  // the error information.
  [Sync] OpenFile(
      mojo_base.mojom.FilePath path, HttpCacheBackendOpenFileFlags flags) =>
      (mojo_base.mojom.File? file, mojo_base.mojom.FileError error);

  // Deletes a file with the given path and returns whether that succeeded.
  [Sync] DeleteFile(mojo_base.mojom.FilePath path,
                    HttpCacheBackendDeleteFileMode mode) => (bool result);

  // Renames a file `from_path` to `to_path`. Returns the error information.
  [Sync] RenameFile(mojo_base.mojom.FilePath from_path,
      mojo_base.mojom.FilePath to_path) => (mojo_base.mojom.FileError error);

  // Returns information about the given path.
  [Sync] GetFileInfo(
      mojo_base.mojom.FilePath path) => (mojo_base.mojom.FileInfo? info);

  // Enumerates files in `path`.
  EnumerateFiles(
      mojo_base.mojom.FilePath path, pending_receiver<FileEnumerator> receiver);

  // Deletes the given directory recursively, asynchronously.
  // This is done by:
  //  1. Renaming the directory to another directory,
  //  2. Returning the result, and
  //  3. Deleting the directory.
  // This means the caller won't know the result of 3.
  CleanupDirectory(mojo_base.mojom.FilePath path) => (bool result);
};

// A factory interface for HttpcacheBackendFileOperations.
interface HttpCacheBackendFileOperationsFactory {
  // Creates a HttpCacheBackendFileOperations.
  Create(pending_receiver<HttpCacheBackendFileOperations> receiver);
};