// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef ZIRCON_SYSTEM_ULIB_FIDL_VISITOR_H_
#define ZIRCON_SYSTEM_ULIB_FIDL_VISITOR_H_

#include <cstdint>
#include <cstdlib>
#include <stdalign.h>
#include <type_traits>
#include <utility>

#include <lib/fidl/coding.h>
#include <lib/fidl/internal.h>
#include <lib/fidl/internal_callable_traits.h>
#include <zircon/assert.h>
#include <zircon/compiler.h>

namespace fidl {

struct NonMutatingVisitorTrait {
    // Types residing in the FIDL message buffer are const
    static constexpr bool kIsConst = true;

    // Message is const
    using ObjectPointerPointer = const void* const* const;
};

struct MutatingVisitorTrait {
    // Types residing in the FIDL message buffer are mutable
    static constexpr bool kIsConst = false;

    // Message is mutable
    using ObjectPointerPointer = void** const;
};

namespace {

// The interface of a FIDL message visitor.
//
// The walker class drives the message traversal, and encoders/decoders/validators etc.
// implement this interface to perform their task.
//
// Visitors should inherit from this class, which has compile-time checks that all visitor interface
// requirements have been met. The walker logic is always parameterized by a concrete implementation
// of this interface, hence there is no virtual method call overhead. MutationTrait is one of
// NonMutatingVisitorTrait or MutatingVisitorTrait.
//
// Many FIDL types do not need special treatment when encoding/decoding. Those that do include:
// - Handles: Transferred to/from handle table.
// - Indirections e.g. nullable fields, strings, vectors: Perform pointer patching.
//
// All pointers passed to the visitor are guaranteed to be alive throughout the duration
// of the message traversal.
// For all callbacks in the visitor, the return value indicates if an error has occurred.
template <typename MutationTrait_, typename StartingPoint_, typename Position_>
class Visitor {
public:
    using MutationTrait = MutationTrait_;

    template <typename T>
    using Ptr = typename std::conditional<MutationTrait::kIsConst,
                                          typename std::add_const<T>::type, T>::type*;

    // A type encapsulating the starting point of message traversal.
    //
    // Implementations must have the following:
    // - Position ToPosition() const, which returns a |Position| located at the starting point.
    using StartingPoint = StartingPoint_;

    // A type encapsulating the position of the walker within the message. This type is parametric,
    // such that the walker does not assume any memory order between objects. |Position| is tracked
    // by the walker at every level of the coding frame, hence we encourage using a smaller type
    // for |Position|, and placing larger immutable values in |StartingPoint|. For example, in the
    // encoder, |StartingPoint| can be a 64-bit buffer address, while |Position| is a 32-bit offset.
    //
    // Implementations must have the following:
    // - Position operator+(uint32_t size) const, to advance position by |size| in the message.
    // - Position& operator+=(uint32_t size), to advance position by |size| in the message.
    // - template <typename T> Ptr<T> Get(StartingPoint start) const, to cast to a suitable pointer.
    using Position = Position_;

    // ObjectPointerPointer is ([const] void*) *[const]
    using ObjectPointerPointer = typename MutationTrait::ObjectPointerPointer;

    // HandlePointer is ([const] zx_handle_t)*
    using HandlePointer = Ptr<zx_handle_t>;

    // EnvelopePointer is ([const] fidl_envelope_t)*
    using EnvelopePointer = Ptr<fidl_envelope_t>;

    // Status returned by visitor callbacks.
    enum class Status {
        kSuccess = 0,
        kConstraintViolationError, // recoverable errors
        kMemoryError               // overflow/out-of-bounds etc. Non-recoverable.
    };

    // Compile-time interface checking. Code is invisible to the subclass.
private:
    // Visit an indirection, which can be the data pointer of a string/vector, the data pointer
    // of an envelope from a table, the pointer in a nullable type, etc.
    // Only called when the pointer is present.
    //
    // |ptr_position|   Position of the pointer.
    // |object_ptr_ptr| Pointer to the data pointer, obtained from |ptr_position.Get(start)|.
    //                  It can be used to patch the pointer.
    // |inline_size|    Size of the inline part of the target object.
    //                  For vectors, this covers the inline part of all the elements.
    //                  It will not contain any trailing padding between objects.
    // |out_position|   Returns the position where the walker will continue its object traversal.
    Status VisitPointer(Position ptr_position,
                        ObjectPointerPointer object_ptr_ptr,
                        uint32_t inline_size,
                        Position* out_position) {
        return Status::kSuccess;
    }

    // Visit a handle. The handle pointer will be mutable if the visitor is mutating.
    // Only called when the handle is present.
    // The handle pointer is derived from |handle_position.Get(start)|.
    Status VisitHandle(Position handle_position, HandlePointer handle_ptr) {
        return Status::kSuccess;
    }

    // Visit a region of padding bytes within message objects. They may be between members of a
    // struct, from after the last member to the end of the struct, or from after a union variant
    // to the end of a union. They should be zero on the wire.
    //
    // N.B. A different type of paddings exist between out-of-line message objects, which are always
    // aligned to |FIDL_ALIGNMENT|. They should be handled accordingly as part of |VisitPointer|.
    //
    // |padding_position| Position of the start of the padding region.
    // |padding_length|   Size of the padding region. It is always positive.
    Status VisitInternalPadding(Position padding_position, uint32_t padding_length) {
        return Status::kSuccess;
    }

    // Called when the walker encounters an envelope.
    // The envelope may be empty or unknown. The implementation should respond accordingly.
    //
    // |payload_type| points to the coding table for the envelope payload. When it is null,
    // either the payload does not require encoding/decoding (e.g. primitives), or the walker
    // has encountered an unknown ordinal.
    //
    // When |EnterEnvelope| returns |Error::kSuccess|, since the data pointer of an envelope is also
    // an indirection, |VisitPointer| will be called on the data pointer. Regardless if the envelope
    // is empty, |LeaveEnvelope| will be called after processing this envelope.
    //
    // Return an error to indicate that the envelope should not be traversed.
    // There will be no corresponding |LeaveEnvelope| call in this case.
    Status EnterEnvelope(Position envelope_position,
                         EnvelopePointer envelope_ptr,
                         const fidl_type_t* payload_type) {
        return Status::kSuccess;
    }

    // Called when the walker finishes visiting all the data in an envelope.
    // Decoder/encoder should validate that the expected number of bytes/handles have been consumed.
    // Linearizer can use this opportunity to set the appropriate num_bytes/num_handles value.
    // It is possible to have nested enter/leave envelope pairs.
    // There will be a matching call to |LeaveEnvelope| for every successful |EnterEnvelope|.
    //
    // |envelope_position| Position of the envelope header.
    // |envelope_ptr|      Pointer to the envelope header that was just processed.
    //                     It is derived from |envelope_position.Get(start)|.
    Status LeaveEnvelope(Position envelope_position, EnvelopePointer envelope_ptr) {
        return Status::kSuccess;
    }

    // Called when a traversal error is encountered on the walker side.
    void OnError(const char* error) {
    }

    template <typename Visitor_, typename ImplSubType_>
    friend constexpr bool CheckVisitorInterface();
};

template <typename Visitor, typename ImplSubType>
constexpr bool CheckVisitorInterface() {
    static_assert(std::is_base_of<Visitor, ImplSubType>::value,
                  "ImplSubType should inherit from fidl::Visitor");

    // kContinueAfterConstraintViolation:
    // - When true, the walker will continue when constraints (e.g. string length) are violated.
    // - When false, the walker will stop upon first error of any kind.
    static_assert(std::is_same<decltype(ImplSubType::kContinueAfterConstraintViolation),
                               const bool>::value,
                  "ImplSubType must declare constexpr bool kContinueAfterConstraintViolation");

    static_assert(std::is_same<
                      typename internal::callable_traits<
                          decltype(&Visitor::StartingPoint::ToPosition)>::return_type,
                      typename Visitor::Position>::value,
                  "Incorrect/missing StartingPoint");

    static_assert(internal::SameInterface<
                      decltype(&Visitor::VisitPointer),
                      decltype(&ImplSubType::VisitPointer)>,
                  "Incorrect/missing VisitPointer");
    static_assert(internal::SameInterface<
                      decltype(&Visitor::VisitHandle),
                      decltype(&ImplSubType::VisitHandle)>,
                  "Incorrect/missing VisitHandle");
    static_assert(internal::SameInterface<
                      decltype(&Visitor::VisitInternalPadding),
                      decltype(&ImplSubType::VisitInternalPadding)>,
                  "Incorrect/missing VisitInternalPadding");
    static_assert(internal::SameInterface<
                      decltype(&Visitor::EnterEnvelope),
                      decltype(&ImplSubType::EnterEnvelope)>,
                  "Incorrect/missing EnterEnvelope");
    static_assert(internal::SameInterface<
                      decltype(&Visitor::LeaveEnvelope),
                      decltype(&ImplSubType::LeaveEnvelope)>,
                  "Incorrect/missing LeaveEnvelope");
    static_assert(internal::SameInterface<
                      decltype(&Visitor::OnError),
                      decltype(&ImplSubType::OnError)>,
                  "Incorrect/missing OnError");
    return true;
}

} // namespace

} // namespace fidl

#endif  // ZIRCON_SYSTEM_ULIB_FIDL_VISITOR_H_