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

module blink.mojom;

import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/read_only_buffer.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "third_party/blink/public/mojom/blob/blob.mojom";
import "third_party/blink/public/mojom/fetch/fetch_api_response.mojom";
import "third_party/blink/public/mojom/fetch/fetch_api_request.mojom";
import "url/mojom/url.mojom";

// This enum is used in histograms, so do not change the ordering and always
// append new types to the end.
// See "CacheStorageErrorType" in enums.xml.
enum CacheStorageError {
  kSuccess = 0,
  kErrorExists = 1,
  kErrorStorage = 2,
  kErrorNotFound = 3,
  kErrorQuotaExceeded = 4,
  kErrorCacheNameNotFound = 5,
  kErrorQueryTooLarge = 6,
  // TODO(cmumford): kErrorNotImplemented is deprecated. Remove use in code.
  kErrorNotImplemented = 7,
  kErrorDuplicateOperation = 8,
  kErrorCrossOriginResourcePolicy = 9,
  // Add new values here.
};

// A result value that may include an optional message string.  The renderer
// may prepend the API method name that produced this result.  If the main
// result value is kSuccess the message may be reported to the console as
// a warning.  If the result value is a failure code then the message string
// will be set as the DOMException's message directly.
struct CacheStorageVerboseError {
  CacheStorageError value;
  string? message;
};

// Controls how requests are matched in the Cache API.
struct CacheQueryOptions {
  bool ignore_search = false;
  bool ignore_method = false;
  bool ignore_vary = false;
};

// Controls how requests are matched in the CacheStorage API.
struct MultiCacheQueryOptions {
  CacheQueryOptions query_options;
  mojo_base.mojom.String16? cache_name;
};

// The type of a single batch operation in the Cache API.
enum OperationType {
  kUndefined,
  kPut,
  kDelete,
};

// A single batch operation for the Cache API.
struct BatchOperation {
  OperationType operation_type;
  blink.mojom.FetchAPIRequest request;

  // If the |operation_type| is kPut, then the |response| must be defined, null
  // otherwise.
  blink.mojom.FetchAPIResponse? response;

  // If the |operation_type| is kDelete, then the |match_options| must be
  // defined, null otherwise.
  CacheQueryOptions? match_options;
};

// EagerResponse: A blob response where the source has eagerly started reading
// the body into a DataPipe.
struct EagerResponse {
  blink.mojom.FetchAPIResponse response;
  handle<data_pipe_consumer> pipe;
  pending_receiver<BlobReaderClient> client_receiver;
};

// Successful Match for both interfaces CacheStorage and CacheStorageCache
// method.
union MatchResponse {
  blink.mojom.FetchAPIResponse response;
  EagerResponse eager_response;
};

struct CacheEntry {
  blink.mojom.FetchAPIRequest request;
  blink.mojom.FetchAPIResponse response;
};

// Handles calls for each individual cache. A cache relates directly to Cache
// defined on spec: https://w3c.github.io/ServiceWorker/#cache-interface
interface CacheStorageCache {
  // Returns the first cached response that matches `request` according to
  // options specified on `query_options`.  `in_related_fetch_event` will be
  // true if the operation was initiated within a FetchEvent handler with
  // a matching request URL. `in_range_fetch_event` will be true if the
  // operation was initiated within a FetchEvent handler with a request
  // range header.
  Match(blink.mojom.FetchAPIRequest request, CacheQueryOptions query_options,
        bool in_related_fetch_event, bool in_range_fetch_event, int64 trace_id)
      => result<MatchResponse, CacheStorageError>;

  // Returns all cached responses that match |request| according to options
  // specified on |query_options|.
  MatchAll(blink.mojom.FetchAPIRequest? request,
           CacheQueryOptions query_options, int64 trace_id)
      => result<array<blink.mojom.FetchAPIResponse>, CacheStorageError>;

  // Returns all pairs of cached (request, response) entries that match
  // |request| according to options specified on |query_options|.
  // Only valid to call for internal browser usage cases, and not for general
  // renderer cache storage web api.
  GetAllMatchedEntries(blink.mojom.FetchAPIRequest? request,
                      CacheQueryOptions query_options, int64 trace_id)
      => result<array<CacheEntry>, CacheStorageError>;

  // Returns all keys (which are requests) of matching |request| and
  // |query_options|.
  Keys(blink.mojom.FetchAPIRequest? request, CacheQueryOptions query_options, int64 trace_id)
      => result<array<blink.mojom.FetchAPIRequest>, CacheStorageError>;

  // Perform a batch of operations, used for PUT and DELETE operations.
  Batch(array<BatchOperation> batch_operations, int64 trace_id)
      => (CacheStorageVerboseError result);

  // Writes the side data (ex: V8 code cache) for the specified cache entry.
  // If it doesn't exist, or the |expected_response_time| differs from the
  // entry's, blink::mojom::CacheStorageError::kErrorNotFound is returned.
  WriteSideData(url.mojom.Url url,
                mojo_base.mojom.Time expected_response_time,
                mojo_base.mojom.BigBuffer data,
                int64 trace_id) => (CacheStorageError result);
};

// Handles global CacheStorage methods, directly relates to methods available on
// spec: https://w3c.github.io/ServiceWorker/#cachestorage-interface
interface CacheStorage {
  // Returns kSuccess if |cache_name| exists or kErrorNotFound if not.
  Has(mojo_base.mojom.String16 cache_name, int64 trace_id) => (CacheStorageError result);

  // Removes a given cache.
  Delete(mojo_base.mojom.String16 cache_name, int64 trace_id) => (CacheStorageError result);

  // Returns all cache names managed on this origin.
  Keys(int64 trace_id) => (array<mojo_base.mojom.String16> keys);

  // Returns the first cached response that matches `request` and
  // `match_options`. It can search on all caches if `cache_name` isn't provided
  // on `match_options`.  `in_related_fetch_event` will be true if the operation
  // was initiated within a FetchEvent handler with a matching request URL.
  // `in_range_fetch_event` will be true if the operation was initiated within a
  // FetchEvent handler with a request range header.
  Match(blink.mojom.FetchAPIRequest request, MultiCacheQueryOptions match_options,
        bool in_related_fetch_event, bool in_range_fetch_event, int64 trace_id)
      => result<MatchResponse, CacheStorageError>;

  // Opens and returns a mojo interface to a cache, it creates if doesn't exist.
  Open(mojo_base.mojom.String16 cache_name, int64 trace_id)
    => result<pending_associated_remote<CacheStorageCache>, CacheStorageError>;
};