google/protobuf/feature_resolver.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2023 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 #ifndef GOOGLE_PROTOBUF_FEATURE_RESOLVER_H__
0009 #define GOOGLE_PROTOBUF_FEATURE_RESOLVER_H__
0010
0011 #include <memory>
0012 #include <string>
0013 #include <utility>
0014 #include <vector>
0015
0016 #include "absl/container/flat_hash_set.h"
0017 #include "absl/status/status.h"
0018 #include "absl/status/statusor.h"
0019 #include "absl/strings/string_view.h"
0020 #include "absl/types/span.h"
0021 #include "google/protobuf/descriptor.h"
0022 #include "google/protobuf/descriptor.pb.h"
0023 #include "google/protobuf/dynamic_message.h"
0024
0025 // Must be included last.
0026 #include "google/protobuf/port_def.inc"
0027
0028 namespace google {
0029 namespace protobuf {
0030
0031 // These helpers implement the unique behaviors of edition features.  For more
0032 // details, see go/protobuf-editions-features.
0033 class PROTOBUF_EXPORT FeatureResolver {
0034  public:
0035   FeatureResolver(FeatureResolver&&) = default;
0036   FeatureResolver& operator=(FeatureResolver&&) = delete;
0037
0038   // Compiles a set of FeatureSet extensions into a mapping of edition to unique
0039   // defaults.  This is the most complicated part of feature resolution, and by
0040   // abstracting this out into an intermediate message, we can make feature
0041   // resolution significantly more portable.
0042   static absl::StatusOr<FeatureSetDefaults> CompileDefaults(
0043       const Descriptor* feature_set,
0044       absl::Span<const FieldDescriptor* const> extensions,
0045       Edition minimum_edition, Edition maximum_edition);
0046
0047   // Creates a new FeatureResolver at a specific edition.  This calculates the
0048   // default feature set for that edition, using the output of CompileDefaults.
0049   static absl::StatusOr<FeatureResolver> Create(
0050       Edition edition, const FeatureSetDefaults& defaults);
0051
0052   // Creates a new feature set using inheritance and default behavior. This is
0053   // designed to be called recursively, and the parent feature set is expected
0054   // to be a fully merged one.  The returned FeatureSet will be fully resolved
0055   // for any extensions that were used to construct the defaults.
0056   absl::StatusOr<FeatureSet> MergeFeatures(
0057       const FeatureSet& merged_parent, const FeatureSet& unmerged_child) const;
0058
0059   // Validates an unresolved FeatureSet object to make sure they obey the
0060   // lifetime requirements.  This needs to run *within* the pool being built, so
0061   // that the descriptors of any feature extensions are known and can be
0062   // validated.  `pool_descriptor` should point to the FeatureSet descriptor
0063   // inside the pool, or nullptr if one doesn't exist,
0064   //
0065   // This will return error messages for any explicitly set features used before
0066   // their introduction or after their removal.  Warnings will be included for
0067   // any explicitly set features that have been deprecated.
0068   struct ValidationResults {
0069     std::vector<std::string> errors;
0070     std::vector<std::string> warnings;
0071   };
0072   static ValidationResults ValidateFeatureLifetimes(
0073       Edition edition, const FeatureSet& features,
0074       const Descriptor* pool_descriptor);
0075
0076  private:
0077   explicit FeatureResolver(FeatureSet defaults)
0078       : defaults_(std::move(defaults)) {}
0079
0080   FeatureSet defaults_;
0081 };
0082
0083 }  // namespace protobuf
0084 }  // namespace google
0085
0086 #endif  // GOOGLE_PROTOBUF_FEATURE_RESOLVER_H__
0087
0088 #include "google/protobuf/port_undef.inc"