swift-protobuf/Sources/SwiftProtobuf/Message.swift

// Sources/SwiftProtobuf/Message.swift - Message support
//
// Copyright (c) 2014 - 2016 Apple Inc. and the project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See LICENSE.txt for license information:
// https://github.com/apple/swift-protobuf/blob/main/LICENSE.txt
//

/// The protocol which all generated protobuf messages implement.
/// `Message` is the protocol type you should use whenever
/// you need an argument or variable which holds "some message".
///
/// Generated messages also implement `Hashable`, and thus `Equatable`.
/// However, the protocol conformance is declared on a different protocol.
/// This allows you to use `Message` as a type directly:
///
///     func consume(message: Message) { ... }
///
/// Instead of needing to use it as a type constraint on a generic declaration:
///
///     func consume<M: Message>(message: M) { ... }
///
/// If you need to convince the compiler that your message is `Hashable` so
/// you can insert it into a `Set` or use it as a `Dictionary` key, use
/// a generic declaration with a type constraint:
///
///     func insertIntoSet<M: Message & Hashable>(message: M) {
///         mySet.insert(message)
///     }
///
/// The actual functionality is implemented either in the generated code or in
/// default implementations of the below methods and properties.
@preconcurrency
public protocol Message: Sendable, CustomDebugStringConvertible {
    /// Creates a new message with all of its fields initialized to their default
    /// values.
    init()

    // Metadata
    // Basic facts about this class and the proto message it was generated from
    // Used by various encoders and decoders

    /// The fully-scoped name of the message from the original .proto file,
    /// including any relevant package name.
    static var protoMessageName: String { get }

    /// True if all required fields (if any) on this message and any nested
    /// messages (recursively) have values set; otherwise, false.
    var isInitialized: Bool { get }

    /// Some formats include enough information to transport fields that were
    /// not known at generation time. When encountered, they are stored here.
    var unknownFields: UnknownStorage { get set }

    //
    // General serialization/deserialization machinery
    //

    /// Decode all of the fields from the given decoder.
    ///
    /// This is a simple loop that repeatedly gets the next field number
    /// from `decoder.nextFieldNumber()` and then uses the number returned
    /// and the type information from the original .proto file to decide
    /// what type of data should be decoded for that field.  The corresponding
    /// method on the decoder is then called to get the field value.
    ///
    /// This is the core method used by the deserialization machinery. It is
    /// `public` to enable users to implement their own encoding formats by
    /// conforming to `Decoder`; it should not be called otherwise.
    ///
    /// Note that this is not specific to binary encodng; formats that use
    /// textual identifiers translate those to field numbers and also go
    /// through this to decode messages.
    ///
    /// - Parameters:
    ///   - decoder: a `Decoder`; the `Message` will call the method
    ///     corresponding to the type of this field.
    /// - Throws: an error on failure or type mismatch.  The type of error
    ///     thrown depends on which decoder is used.
    mutating func decodeMessage<D: Decoder>(decoder: inout D) throws

    /// Traverses the fields of the message, calling the appropriate methods
    /// of the passed `Visitor` object.
    ///
    /// This is used internally by:
    ///
    /// * Protobuf binary serialization
    /// * JSON serialization (with some twists to account for specialty JSON)
    /// * Protobuf Text serialization
    /// * `Hashable` computation
    ///
    /// Conceptually, serializers create visitor objects that are
    /// then passed recursively to every message and field via generated
    /// `traverse` methods.  The details get a little involved due to
    /// the need to allow particular messages to override particular
    /// behaviors for specific encodings, but the general idea is quite simple.
    func traverse<V: Visitor>(visitor: inout V) throws

    // Standard utility properties and methods.
    // Most of these are simple wrappers on top of the visitor machinery.
    // They are implemented in the protocol, not in the generated structs,
    // so can be overridden in user code by defining custom extensions to
    // the generated struct.

    /// An implementation of hash(into:) to provide conformance with the
    /// `Hashable` protocol.
    func hash(into hasher: inout Hasher)

    /// Helper to compare `Message`s when not having a specific type to use
    /// normal `Equatable`. `Equatable` is provided with specific generated
    /// types.
    func isEqualTo(message: any Message) -> Bool

    // TODO: I am *temporarily* making this a protocol requirement so that I can replace its
    // implementation in generated table-driven messages. That will let me support decoding in all
    // of its forms (init a new message, merge into an existing message) by only generating this
    // `_merge` method instead of multiple initializers and methods. This will be removed once the
    // implementation is far enough along that I can regenerate the WKTs and plugin protos, since
    // everything will be moved into the runtime at that point.
    mutating func _merge(
        rawBuffer body: UnsafeRawBufferPointer,
        extensions: (any ExtensionMap)?,
        partial: Bool,
        options: BinaryDecodingOptions
    ) throws
}

extension Message {
    /// Generated proto2 messages that contain required fields, nested messages
    /// that contain required fields, and/or extensions will provide their own
    /// implementation of this property that tests that all required fields are
    /// set. Users of the generated code SHOULD NOT override this property.
    public var isInitialized: Bool {
        // The generated code will include a specialization as needed.
        true
    }

    /// A hash based on the message's full contents.
    public func hash(into hasher: inout Hasher) {
        var visitor = HashVisitor(hasher)
        try? traverse(visitor: &visitor)
        hasher = visitor.hasher
    }

    /// A description generated by recursively visiting all fields in the message,
    /// including messages.
    public var debugDescription: String {
        #if DEBUG
        // TODO Ideally there would be something like serializeText() that can
        // take a prefix so we could do something like:
        //   [class name](
        //      [text format]
        //   )
        let className = String(reflecting: type(of: self))
        let header = "\(className):\n"
        return header + textFormatString()
        #else
        return String(reflecting: type(of: self))
        #endif
    }

    /// Creates an instance of the message type on which this method is called,
    /// executes the given block passing the message in as its sole `inout`
    /// argument, and then returns the message.
    ///
    /// This method acts essentially as a "builder" in that the initialization of
    /// the message is captured within the block, allowing the returned value to
    /// be set in an immutable variable. For example,
    ///
    ///     let msg = MyMessage.with { $0.myField = "foo" }
    ///     msg.myOtherField = 5  // error: msg is immutable
    ///
    /// - Parameter populator: A block or function that populates the new message,
    ///   which is passed into the block as an `inout` argument.
    /// - Returns: The message after execution of the block.
    public static func with(
        _ populator: (inout Self) throws -> Void
    ) rethrows -> Self {
        var message = Self()
        try populator(&message)
        return message
    }
}

/// Implementation base for all messages; not intended for client use.
///
/// In general, use `SwiftProtobuf.Message` instead when you need a variable or
/// argument that can hold any type of message. Occasionally, you can use
/// `SwiftProtobuf.Message & Equatable` or `SwiftProtobuf.Message & Hashable` as
/// generic constraints if you need to write generic code that can be applied to
/// multiple message types that uses equality tests, puts messages in a `Set`,
/// or uses them as `Dictionary` keys.
@preconcurrency
public protocol _MessageImplementationBase: Message, Hashable {
    // This is an implementation detail of the runtime; users should not call it. The return type
    // is a class-bound existential because the true SPI type cannot be used in a protocol
    // requirement.
    func _protobuf_messageStorage(accessToken: _MessageStorageToken) -> AnyObject

    // This is an implementation detail of the runtime; users should not call it.
    mutating func _protobuf_ensureUniqueStorage(accessToken: _MessageStorageToken)

    // Legacy function; no longer used, but left to maintain source compatibility.
    func _protobuf_generated_isEqualTo(other: Self) -> Bool
}

extension _MessageImplementationBase {
    // TODO: Remove this default implementation once we're generating all the WKTs with the new
    // implementation.
    public func _protobuf_messageStorage(accessToken: _MessageStorageToken) -> AnyObject {
        fatalError()
    }

    // TODO: Remove this default implementation once we're generating all the WKTs with the new
    // implementation.
    public mutating func _protobuf_ensureUniqueStorage(accessToken: _MessageStorageToken) {
        fatalError()
    }

    public func isEqualTo(message: any Message) -> Bool {
        guard let other = message as? Self else {
            return false
        }
        return self == other
    }

    // Legacy default implementation that is used by old generated code, current
    // versions of the plugin/generator provide this directly, but this is here
    // just to avoid breaking source compatibility.
    public static func == (lhs: Self, rhs: Self) -> Bool {
        lhs._protobuf_generated_isEqualTo(other: rhs)
    }

    // Legacy function that is generated by old versions of the plugin/generator,
    // defaulted to keep things simple without changing the api surface.
    public func _protobuf_generated_isEqualTo(other: Self) -> Bool {
        self == other
    }
}

extension _MessageImplementationBase {
    /// Convenience property for the runtime to retrieve the underlying storage for a concretely
    /// typed message.
    internal var storageForRuntime: _MessageStorage {
        unsafeDowncast(_protobuf_messageStorage(accessToken: _MessageStorageToken()), to: _MessageStorage.self)
    }
}