chromium/content/browser/security/coop/coop_related_group.h

// Copyright 2023 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_SECURITY_COOP_COOP_RELATED_GROUP_H_
#define CONTENT_BROWSER_SECURITY_COOP_COOP_RELATED_GROUP_H_

#include <optional>
#include <vector>

#include "base/memory/ref_counted.h"
#include "base/memory/scoped_refptr.h"
#include "content/browser/url_info.h"
#include "content/browser/web_exposed_isolation_info.h"
#include "content/common/content_export.h"
#include "url/origin.h"

namespace content {

class BrowserContext;
class BrowsingInstance;
class SiteInstanceImpl;

// A CoopRelatedGroup is a set of browsing context groups that can communicate
// with each other via a limited subset of properties
// (currently window.postMessage() and window.closed). Documents in
// BrowsingContexts that are not part of the same CoopRelatedGroup cannot get
// references to each other's Window by any means at all. CoopRelatedGroup,
// browsing context groups (BrowsingInstances) and Agent Clusters (roughly, but
// not strictly equivalent to SiteInstances) provide three tiers of
// communication capabilities:
// - Documents in the same Agent Cluster can synchronously DOM script each
//   other.
// - Documents in the same browsing context group can asynchronously interact
//   with each other, via cross-origin Window properties.
// - Documents in the same CoopRelatedGroup can only message each
//   other and observe window.closed.
//
// These layers have a 1->n relationship pattern: a CoopRelatedGroup contains 1
// or more browsing context groups, itself containing 1 or more agent clusters.
// Each layer is refcounted and therefore kept alive by the layer below it, with
// individual SiteInstances at the base, being kept alive manually.
//
// When no document inside a browsing context group sets COOP:
// restrict-properties, the CoopRelatedGroup contains only a single browsing
// context group. CoopRelatedGroups containing more than a single browsing
// context group occur when COOP: restrict-properties forces a browsing context
// group swap in the same CoopRelatedGroup. It allows retaining a relationship
// to the opener across browsing context groups, hence creating the actual
// communication channel.
//
// Like BrowsingInstance, CoopRelatedGroup has no public members, as it is
// designed to be interacted with only from the BrowsingInstance class, itself
// only reachable from SiteInstance. To get a new SiteInstance that is part of
// the same CoopRelatedGroup but in a different BrowsingInstance, use
// SiteInstanceImpl::GetCoopRelatedSiteInstance. Because of this,
// CoopRelatedGroups are tested in site_instance_impl_unittest.cc.
class CONTENT_EXPORT CoopRelatedGroup final
    : public base::RefCounted<CoopRelatedGroup> { … };

}  // namespace content

#endif  // CONTENT_BROWSER_SECURITY_COOP_COOP_RELATED_GROUP_H_;