// 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 storage.mojom;

enum DisallowInactiveClientReason {
  // Used when a new connection is being opened with a higher version
  // number which triggers a version change event being sent to existing
  // connections.
  kVersionChangeEvent = 0,
  // Used when a transaction first attempts to acquire locks (disallowing
  // whatever client may hold that lock from becoming inactive).
  kTransactionIsAcquiringLocks = 1,
  // Used when a transaction starts while its client is already inactive.
  // This potentially kicks the client out of BFCache since the transaction
  // won't be able to proceed.
  kTransactionIsStartingWhileBlockingOthers = 2,
  // Similar to above, but used when a transaction is ongoing and its client
  // becomes inactive.
  kTransactionIsOngoingAndBlockingOthers = 3,
};

// IndexedDB clients live in the renderer and talk directly to the storage
// service, but some clients may be inactive (e.g. in a BFCached document).
// In order to correctly handle IndexedDB interactions with the inactive
// documents, there is also a corresponding storage service -> browser
// process interface for each IndexedDB client.
interface IndexedDBClientStateChecker {
  // Check if the client is currently in inactive states that shouldn't
  // receive certain callbacks/events (e.g. those that might block the
  // IndexedDB flow such as `VersionChange`) from the IndexedDB service.
  // For the client without an associated RenderFrameHost, this should report
  // the value indicating that the client is active. A reason needs to be
  // provided to this call, which will be passed to the actual method that
  // processes the disallow action.
  // For the client with an associated RenderFrameHost, this call may also have
  // side effects:
  // 1. If the client is active, it may be disallowed from entering some
  // inactive states (e.g. BFCache);
  // 2. If the client is in some inactive state (e.g. BFCache), it will be
  // disallowed from being activated again in the future.
  // See `RenderFrameHost::IsInactiveAndDisallowActivation()`.
  // `keep_active` is used to keep an active client away from entering
  // the inactive state if while it's valid and connected.
  // This has no effect if the client is no longer active by the time the IPC
  // message is handled.
  DisallowInactiveClient(
      int32 connection_id,
      DisallowInactiveClientReason reason,
      pending_receiver<IndexedDBClientKeepActive>? keep_active)
      => (bool was_active);

  // Binds another mojo connection to `this`.
  MakeClone(pending_receiver<IndexedDBClientStateChecker> receiver);

  // Summary of allowed state transitions under different scenarios.
  // There are three possible states for the IndexedDB client: active,
  // inactive and destroyed.

  // In the default case, the following transactions are allowed:
  // - active -> inactive
  // - active -> destroyed
  // - inactive -> active
  // - inactive -> destroyed

  // After `DisallowInactiveClient` has been called, the following transitions
  // are allowed:
  // - active -> destroyed
  // - inactive -> destroyed
  // Additionally, if `keep_active` is not set or goes out of scope, the
  // following transition will be allowed as well:
  // - active -> inactive
};

// Preventing an instance of this interface from entering some inactive state
// like BFCache. Closing the other end (i.e. the remote) ends the scope
// associated with the instance.
interface IndexedDBClientKeepActive {};