services/network/public/mojom/chunked_data_pipe_getter.mojom

// Copyright 2018 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;

// Interface that wraps a data stream and allows it to be read via a data pipe.
// Note that unlike DataPipeGetter, the size may not be known in advance.
//
// This is only used for chunked uploads, which send a final empty chunk to
// indicate the end of the response, instead of using a Content-Length header.
// For all web-exposed APIs, the upload body size is known in advance, so it's
// unclear how many servers support chunked uploads. As a result, it's
// recommended this class only be used with servers known to support chunked
// uploads.
//
// Knowing the size in advance also allows servers to know if the upload is
// bigger than they're willing to accept, and cancel the request early, which is
// a more friendly behavior.
interface ChunkedDataPipeGetter {
  // Requests the total size of the data that will be provided by the data pipe.
  // The Getter may invoke the callback any time, before, during, or after
  // providing data through the pipe. On error, |status| should be populated
  // with a net::Error value.
  //
  // Will be called only once, before StartReading() is invoked.
  GetSize() => (int32 status, uint64 size);

  // Starts reading from the beginning of the wrapped stream and writing it into
  // the producer handle |pipe|. Will only be called after GetSize(), but unlike
  // GetSize(), may be invoked multiple times. Data should only be written to the
  // |pipe| that StartReading() was most recently called with; any previously
  // passed pipes can be discarded and no longer need to be be written to.
  StartReading(handle<data_pipe_producer> pipe);
};