ContentAnalysisBackend.h

Enable keyboard shortcuts

/* This Source Code Form is subject to the terms of the Mozilla Public

 * License, v. 2.0. If a copy of the MPL was not distributed with this

 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_contentanalysisbackend_h

#define mozilla_contentanalysisbackend_h

#include "mozilla/MozPromise.h"

#include "mozilla/RefPtr.h"

#include "nsIContentAnalysis.h"

#include "nsISupportsImpl.h"

#include "nsStringFwd.h"

namespace mozilla::contentanalysis {

class ContentAnalysisDiagnosticInfo;

class ContentAnalysisResponse;

// Abstract interface representing a content-analysis verdict engine.

//

// ContentAnalysis owns one ContentAnalysisBackend and delegates per-request

// analysis, acknowledgement, cancellation, and diagnostics to it.

class ContentAnalysisBackend {

 public:

  NS_INLINE_DECL_THREADSAFE_REFCOUNTING(ContentAnalysisBackend)

  ContentAnalysisBackend() = default;

  ContentAnalysisBackend(const ContentAnalysisBackend&) = delete;

  ContentAnalysisBackend& operator=(const ContentAnalysisBackend&) = delete;

  using DiagnosticInfoPromise =

      MozPromise<RefPtr<ContentAnalysisDiagnosticInfo>, nsresult, true>;

  // Kick off backend initialization if necessary (e.g. connect to an agent,

  // fetch and load a module). Returns synchronously when backend is ready to

  // receive requests, even if backend may continue further initialization

  // asynchronously. Concurrent calls are safe.

  virtual nsresult EnsureReady() = 0;

  // Analyze a single request and produce a verdict. The returned promise

  // resolves on the main thread with a populated ContentAnalysisResponse, or

  // rejects with an nsresult on error.

  virtual nsresult Analyze(nsCOMPtr<nsIContentAnalysisRequest> aRequest,

                           bool aAutoAcknowledge) = 0;

  // Acknowledge a previously issued response. Backends with no out-of-process

  // counterparty may treat this as a no-op.

  virtual nsresult Acknowledge(

      nsCOMPtr<nsIContentAnalysisAcknowledgement> aAcknowledgement,

      const nsACString& aRequestToken) = 0;

  // Cancel a user action, which may cause in-flight requests with the same user

  // action ID to be canceled as well.

  virtual void CancelUserAction(const nsACString& aUserActionId) = 0;

  // Surface diagnostics for nsIContentAnalysis::getDiagnosticInfo. May resolve

  // with info indicating successful or failure status; rejects with the

  // nsresult in the case status cannot be determined.

  virtual RefPtr<DiagnosticInfoPromise> GetDiagnosticInfo() = 0;

  // Release backend resources. Called during xpcom-shutdown-threads.

  virtual void Shutdown() = 0;

  // Test hook backing nsIContentAnalysis::forceRecreateClientForTest. Default

  // no-op for backends without persistent connection state.

  virtual nsresult ForceReinitializeForTest() { return NS_OK; }

  // Test hook backing nsIContentAnalysis::GetCreatingClientForTest. Returns

  // true if the backend is currently in the middle of an async client/module

  // creation step. Default false for backends without persistent connection

  // state.

  virtual bool IsCreatingClientForTest() const { return false; }

  // Called by ContentAnalysis when browser.contentanalysis.max_connections

  // changes. Default no-op for backends that don't use a connection pool.

  virtual void OnMaxConnectionsPrefChanged() {}

  // True if an in-flight dispatch is tracking aRequestToken to await a

  // response. The default returns false for backends whose Analyze is

  // synchronous from the framework's perspective (response is delivered before

  // any caller could ask this question). Backends that asynchronously correlate

  // responses by request_token override this.

  virtual bool IsResponsePendingForRequest(const nsACString& aRequestToken) {

    return false;

 protected:

  virtual ~ContentAnalysisBackend() = default;

};

}  // namespace mozilla::contentanalysis

#endif  // mozilla_contentanalysisbackend_h