chromium/content/browser/loader/url_loader_factory_utils.h

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

#ifndef CONTENT_BROWSER_LOADER_URL_LOADER_FACTORY_UTILS_H_
#define CONTENT_BROWSER_LOADER_URL_LOADER_FACTORY_UTILS_H_

#include "base/memory/stack_allocated.h"
#include "content/browser/devtools/devtools_instrumentation.h"
#include "content/common/content_export.h"
#include "content/public/browser/content_browser_client.h"
#include "services/network/public/cpp/url_loader_factory_builder.h"

namespace net {
class IsolationInfo;
}

namespace content {

class StoragePartitionImpl;

namespace url_loader_factory {

Interceptor;

// This method must be called on the UI thread.
CONTENT_EXPORT const Interceptor& GetTestingInterceptor();

// Allows intercepting the URLLoaderFactory creation.
// For every `SetInterceptorForTesting(non-null interceptor)`,
// `SetInterceptorForTesting({})` must be called to ensure restoring the default
// behavior.
// This method must be called either on the UI thread or before threads start.
// This callback is run on the UI thread.
// TODO(crbug.com/40947547): Document when the interception occurs.
CONTENT_EXPORT void SetInterceptorForTesting(const Interceptor& interceptor);

// Only accessed on the IO thread.
// Basically the same as `!!GetTestingInterceptor()`, and introduced to avoid
// possible race conditions between UI/IO threads.
CONTENT_EXPORT bool HasInterceptorOnIOThreadForTesting();
CONTENT_EXPORT void SetHasInterceptorOnIOThreadForTesting(bool has_interceptor);

// A parameter object for `ContentBrowserClient::WillCreateURLLoaderFactory()`.
class CONTENT_EXPORT ContentClientParams final { … };

// When `kAllow` is used, non-null `header_client`, `disable_secure_dns` and
// `factory_override` (respectively) are passed to
// `ContentBrowserClient::WillCreateURLLoaderFactory()` and
// `devtools_instrumentation`.
// Otherwise (`kDisallow`), nullptr are passed.
enum class HeaderClientOption { … };
enum class DisableSecureDnsOption { … };
enum class FactoryOverrideOption { … };

// Specifies the final destination of the URLLoaderFactory in `Create()`.
class CONTENT_EXPORT TerminalParams final { … };

// Creates a URLLoaderFactory, intercepted by:
// 1. `ContentBrowserClient::WillCreateURLLoaderFactory()`
//    (if `content_client_params` is non-nullopt),
// 2. `devtools_instrumentation` (if `devtools_params` is non-nullopt)
// 3. `GetInterceptor()`
//    (see the comments in the .cc file for detailed conditions)
// and then finally routed as specified by `TerminalParams`.
//
// The created URLLoaderFactory is
// - Returned as `scoped_refptr<network::SharedURLLoaderFactory>`,
// - Returned as `mojo::PendingRemote<network::mojom::URLLoaderFactory>`, or
// - Connected to `receiver_to_connect`,
// respectively for the variants below.
//
// Note that the created URLLoaderFactory might NOT support auto-reconnect after
// a crash of Network Service.
[[nodiscard]] CONTENT_EXPORT scoped_refptr<network::SharedURLLoaderFactory>
Create(ContentBrowserClient::URLLoaderFactoryType type,
       TerminalParams terminal_params,
       std::optional<ContentClientParams> content_client_params = std::nullopt,
       std::optional<devtools_instrumentation::WillCreateURLLoaderFactoryParams>
           devtools_params = std::nullopt);

[[nodiscard]] CONTENT_EXPORT mojo::PendingRemote<
    network::mojom::URLLoaderFactory>
CreatePendingRemote(
    ContentBrowserClient::URLLoaderFactoryType type,
    TerminalParams terminal_params,
    std::optional<ContentClientParams> content_client_params = std::nullopt,
    std::optional<devtools_instrumentation::WillCreateURLLoaderFactoryParams>
        devtools_params = std::nullopt);

CONTENT_EXPORT void CreateAndConnectToPendingReceiver(
    mojo::PendingReceiver<network::mojom::URLLoaderFactory> receiver_to_connect,
    ContentBrowserClient::URLLoaderFactoryType type,
    TerminalParams terminal_params,
    std::optional<ContentClientParams> content_client_params = std::nullopt,
    std::optional<devtools_instrumentation::WillCreateURLLoaderFactoryParams>
        devtools_params = std::nullopt);

}  // namespace url_loader_factory
}  // namespace content

#endif  // CONTENT_BROWSER_LOADER_URL_LOADER_FACTORY_UTILS_H_