components/push_messaging/app_identifier.h

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

#ifndef COMPONENTS_PUSH_MESSAGING_APP_IDENTIFIER_H_
#define COMPONENTS_PUSH_MESSAGING_APP_IDENTIFIER_H_

#include <stddef.h>
#include <stdint.h>

#include <optional>
#include <string>
#include <vector>

#include "base/check.h"
#include "base/gtest_prod_util.h"
#include "base/time/time.h"
#include "url/gurl.h"

namespace push_messaging {

// The prefix used for all push messaging application ids.
extern const char kAppIdentifierPrefix[];
extern const size_t kPrefixLength;

// Ok to use '#' as separator since only the origin of the url is used.
inline constexpr char kPrefValueSeparator = '#';

inline constexpr size_t kGuidLength = 36;  // "%08X-%04X-%04X-%04X-%012llX"

// Type used to identify a Service Worker registration from a Push API
// perspective. These can be persisted to prefs, in a 1:1 mapping between
// app_id (which includes origin) and service_worker_registration_id.
// Legacy mapped values saved by old versions of Chrome are also supported;
// these don't contain the origin in the app_id, so instead they map from
// app_id to pair<origin, service_worker_registration_id>.
//
// See //chrome/browser/push_messaging/push_messaging_app_identifier.h for the
// chrome integration, this class itself does not rely on //chrome.
class AppIdentifier final {
 public:
  // Returns whether the modern InstanceID API should be used with this app_id
  // (rather than legacy GCM registration).
  static bool UseInstanceID(const std::string& app_id);

  // Generates a new app identifier, with partially random app_id.
  static AppIdentifier Generate(
      const GURL& origin,
      int64_t service_worker_registration_id,
      const std::optional<base::Time>& expiration_time = std::nullopt);

  // Creates an invalid AppIdentifier which will return is_null() and fail on
  // DCheckValid(), accessing any fields triggers DCheck failure.
  static AppIdentifier GenerateInvalid();

  // Creates an AppIdentifier by directly forwarding the parameters to the
  // constructor; the returned AppIdentifier instance will be checked by
  // DCheckValid().
  static AppIdentifier GenerateDirect(
      const std::string& app_id,
      const GURL& origin,
      int64_t service_worker_registration_id,
      const std::optional<base::Time>& expiration_time = std::nullopt);

  // Returns true if this identifier does not represent an app (i.e. this was
  // returned by a failed Find call).
  bool is_null() const { return service_worker_registration_id_ < 0; }

  // String that should be passed to push services like GCM to identify a
  // particular Service Worker (so we can route incoming messages). Example:
  // wp:https://foo.example.com:8443/#9CC55CCE-B8F9-4092-A364-3B0F73A3AB5F
  // Legacy app_ids have no origin, e.g. wp:9CC55CCE-B8F9-4092-A364-3B0F73A3AB5F
  const std::string& app_id() const {
    DCHECK(!is_null());
    return app_id_;
  }

  const GURL& origin() const {
    DCHECK(!is_null());
    return origin_;
  }

  int64_t service_worker_registration_id() const {
    DCHECK(!is_null());
    return service_worker_registration_id_;
  }

  void set_expiration_time(const std::optional<base::Time>& expiration_time) {
    expiration_time_ = expiration_time;
  }

  bool IsExpired() const;

  std::optional<base::Time> expiration_time() const {
    DCHECK(!is_null());
    return expiration_time_;
  }

  // Validates that all the fields contain valid values.
  void DCheckValid() const;

 private:
  friend class AppIdentifierTestSupport;

  static AppIdentifier GenerateInternal(
      const GURL& origin,
      int64_t service_worker_registration_id,
      bool use_instance_id,
      const std::optional<base::Time>& expiration_time = std::nullopt);

  // Constructs an invalid app identifier.
  AppIdentifier();

  // Constructs a valid app identifier.
  AppIdentifier(
      const std::string& app_id,
      const GURL& origin,
      int64_t service_worker_registration_id,
      const std::optional<base::Time>& expiration_time = std::nullopt);

  std::string app_id_;
  GURL origin_;
  int64_t service_worker_registration_id_;
  std::optional<base::Time> expiration_time_;
};

}  // namespace push_messaging

#endif  // COMPONENTS_PUSH_MESSAGING_APP_IDENTIFIER_H_