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

module storage.mojom;

import "mojo/common/file.mojom";
import "mojo/common/file_path.mojom";
import "mojo/common/time.mojom";
import "url/mojo/url.mojom";

// Interface that can be implemented to be informed of certain information while
// reading the data for a blob.
interface BlobReaderClient {
  // Called when the size of the blob being read has been calculated:
  //   |total_size| is the total size of the blob.
  //   |expected_content_size| is how many bytes should be sent over the data
  //      pipe, taking into account a range if the blob was read with ReadRange.
  // If an error occurs while reading the blob, this method might not get called.
  OnCalculatedSize(uint64 total_size,
                   uint64 expected_content_size);

  // Called when reading the blob finished (with success or failure). Status is
  // a net::Error indicating any potential error that might have occurred,
  // |data_length| tells the reader how many bytes were written into the data
  // pipe, and can be used as a sanity check to make sure all bytes were
  // received.
  OnComplete(int32 status, uint64 data_length);
};

// This interface provides access to a blob in the blob system.
interface Blob {
  // Creates a copy of this Blob reference.
  Clone(Blob& blob);

  // Causes the entire contents of this blob to be written into the given data
  // pipe. An optional BlobReaderClient will be informed of the result of the
  // read operation.
  ReadAll(handle<data_pipe_producer> pipe, BlobReaderClient? client);

  // Causes a subrange of the contents of this blob to be written into the given
  // data pipe. An optional BlobReaderClient will be informed of the result of
  // the read operation.
  ReadRange(uint64 offset, uint64 length, handle<data_pipe_producer> pipe,
            BlobReaderClient? client);

  // This method is an implementation detail of the blob system. You should not
  // ever need to call it directly.
  // This returns the internal UUID of the blob, used by the blob system to
  // identify the blob.
  GetInternalUUID() => (string uuid);
};

// An opaque handle passed from the browser process to a child process to
// manage the lifetime of the returned Blob URL. The URL is revoked when
// this handle is dropped.
interface BlobURLHandle {
};

// This interface is the primary access point from renderer to the browser's blob system.
// This interface provides methods to register new blobs and get references to existing blobs.
interface BlobRegistry {
  // Registers a new blob with the blob registry.
  // TODO(mek): Make this method non-sync and get rid of the UUID parameter once
  // enough of the rest of the system doesn't rely on the UUID anymore.
  [Sync] Register(Blob& blob, string uuid,
                  string content_type, string content_disposition,
                  array<DataElement> elements) => ();

  // Registers a public Blob URL with the blob registry.
  // TODO(kinuko,mek): This should probably create and return a new blob: URL rather
  // than letting the caller in the renderer provide one.
  [Sync] RegisterURL(Blob blob, url.mojom.Url url) => (BlobURLHandle url_handle);

  // Returns a reference to an existing blob. Should not be used by new code,
  // is only exposed to make converting existing blob using code easier.
  GetBlobFromUUID(Blob& blob, string uuid);
};

// A blob is built up of elements of various types.
union DataElement {
  // Bytes send asynchronously at the request of the blob registry.
  DataElementBytes bytes;
  // A reference to a file on disk.
  DataElementFile file;
  // A reference to a file as a filesystem URL.
  DataElementFilesystemURL file_filesystem;
  // A reference to another blob.
  DataElementBlob blob;
};

// Bytes send asynchronously at the request of the blob registry. Can
// optionally also directly contain the data, in which case the blob registry
// can decide to either use the embedded data or later request the data again.
struct DataElementBytes {
  // Maximum size of all DataElementBytes that have embedded data included in
  // any particular call to register a new blob.
  // Equivalent in meaning to storage::kDefaultIPCMemorySize.
  const uint64 kMaximumEmbeddedDataSize = 256000;

  // Size of the data.
  uint64 length;
  // Optionally embedded data. If present, the size of this array should be
  // equal to |length|.
  array<uint8>? embedded_data;
  // Interface through which the blob registry can request the data.
  BytesProvider data;
};

// Interface through which the blob registry can request data when it is ready
// for it.
interface BytesProvider {
  // Requests all the data provided by this provider as an array in the reply.
  // The size of this array must match the length attribute of the
  // DataElementBytes struct this provider was associated with.
  // If this method is called, it is called exactly once, and none of the other
  // methods will be called.
  RequestAsReply() => (array<uint8> data);

  // Requests all the data provided by this provider to be transfered on a data
  // pipe. The amount of data transfered should match the length attribute of
  // the DataElementBytes struct this provider was associated with.
  // If this method is called, it is called exactly once, and none of the other
  // methods will be called.
  RequestAsStream(handle<data_pipe_producer> pipe);

  // Requests the provider to write a slice of the data provided by this
  // provider to the given file at the given offset. When the data is written
  // the callback should be invoked with the new modification time of the file.
  // If this method is called, it can be called multiple times, but none of the
  // other methods will be called.
  // If writing for whatever reason fails, the callback is called without a
  // modification time.
  RequestAsFile(uint64 source_offset, uint64 source_size,
                mojo.common.mojom.File file, uint64 file_offset)
      => (mojo.common.mojom.Time? time_file_modified);
};

// A reference to a slice of a file on disk.
struct DataElementFile {
  // Path of the file.
  mojo.common.mojom.FilePath path;
  // Offset inside the file.
  uint64 offset;
  // Length of the slice. Can be uint64_max if the length is unknown. If this is
  // the case the offset is always 0 and this DataElement should be the only
  // element making up the blob.
  uint64 length;
  // Expected modification time of the file being referenced. Can be null if the
  // modification time is unknown.
  mojo.common.mojom.Time? expected_modification_time;
};

// A reference to a slice of a file as a filesystem URL.
struct DataElementFilesystemURL {
  // URL of the file.
  url.mojom.Url url;
  // Offset inside the file.
  uint64 offset;
  // Length of the slice. Can be uint64_max if the length is unknown. If this is
  // the case the offset is always 0 and this DataElement should be the only
  // element making up the blob.
  uint64 length;
  // Expected modification time of the file being referenced. Can be null if the
  // modification time is unknown.
  mojo.common.mojom.Time? expected_modification_time;
};

// A reference to a slice of another blob.
struct DataElementBlob {
  // The blob being referenced.
  Blob blob;
  // Offset to the beginning of the slice.
  uint64 offset;
  // Length of the slice.
  uint64 length;
};