rippled/include/xrpl/basics/random.h

#pragma once

#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/beast/xor_shift_engine.h>

#include <cstdint>
#include <limits>
#include <mutex>
#include <random>
#include <type_traits>

namespace xrpl {

#ifndef __INTELLISENSE__
static_assert(
    // NOLINTNEXTLINE(misc-redundant-expression)
    std::is_integral_v<beast::xor_shift_engine::result_type> &&
        std::is_unsigned_v<beast::xor_shift_engine::result_type>,
    "The XRPL default PRNG engine must return an unsigned integral type.");

static_assert(
    // NOLINTNEXTLINE(misc-redundant-expression)
    std::numeric_limits<beast::xor_shift_engine::result_type>::max() >=
        std::numeric_limits<std::uint64_t>::max(),
    "The XRPL default PRNG engine return must be at least 64 bits wide.");
#endif

namespace detail {

// Determines if a type can be called like an Engine
// NOLINTNEXTLINE(readability-redundant-typename): typename required by MSVC
template <class Engine, class Result = typename Engine::result_type>
using is_engine = std::is_invocable_r<Result, Engine>;
}  // namespace detail

/**
 * Return the default random engine.
 *
 * This engine is guaranteed to be deterministic, but by
 * default will be randomly seeded. It is NOT cryptographically
 * secure and MUST NOT be used to generate randomness that
 * will be used for keys, secure cookies, IVs, padding, etc.
 *
 * Each thread gets its own instance of the engine which
 * will be randomly seeded.
 */
inline beast::xor_shift_engine&
defaultPrng()
{
    // This is used to seed the thread-specific PRNGs on demand
    static beast::xor_shift_engine kSeeder = [] {
        std::random_device rng;
        std::uniform_int_distribution<std::uint64_t> distribution{1};
        return beast::xor_shift_engine(distribution(rng));
    }();

    // This protects the seeder
    static std::mutex kM;

    // The thread-specific PRNGs:
    thread_local beast::xor_shift_engine kEngine = [] {
        std::uint64_t seed = 0;
        {
            std::scoped_lock const lk(kM);
            std::uniform_int_distribution<std::uint64_t> distribution{1};
            seed = distribution(kSeeder);
        }
        return beast::xor_shift_engine{seed};
    }();

    return kEngine;
}

/**
 * Return a uniformly distributed random integer.
 *
 * @param min The smallest value to return. If not specified
 *            the value defaults to 0.
 * @param max The largest value to return. If not specified
 *            the value defaults to the largest value that
 *            can be represented.
 *
 * The randomness is generated by the specified engine (or
 * the default engine if one is not specified). The result
 * is cryptographically secure only when the engine passed
 * into the function is cryptographically secure.
 *
 * @note The range is always a closed interval, so calling
 *       rand_int(-5, 15) can return any integer in the
 *       closed interval [-5, 15]; similarly, calling
 *       rand_int(7) can return any integer in the closed
 *       interval [0, 7].
 */
/** @{ */
template <class Engine, class Integral>
Integral
randInt(Engine& engine, Integral min, Integral max)
    requires(std::is_integral_v<Integral> && detail::is_engine<Engine>::value)
{
    XRPL_ASSERT(max > min, "xrpl::randInt : max over min inputs");

    // This should have no state and constructing it should
    // be very cheap. If that turns out not to be the case
    // it could be hand-optimized.
    return std::uniform_int_distribution<Integral>(min, max)(engine);
}

template <class Integral>
Integral
randInt(Integral min, Integral max)
    requires(std::is_integral_v<Integral>)
{
    return randInt(defaultPrng(), min, max);
}

template <class Engine, class Integral>
Integral
randInt(Engine& engine, Integral max)
    requires(std::is_integral_v<Integral> && detail::is_engine<Engine>::value)
{
    return randInt(engine, Integral(0), max);
}

template <class Integral>
Integral
randInt(Integral max)
    requires(std::is_integral_v<Integral>)
{
    return randInt(defaultPrng(), max);
}

template <class Integral, class Engine>
Integral
randInt(Engine& engine)
    requires(std::is_integral_v<Integral> && detail::is_engine<Engine>::value)
{
    return randInt(engine, std::numeric_limits<Integral>::max());
}

template <class Integral = int>
Integral
randInt()
    requires(std::is_integral_v<Integral>)
{
    return randInt(defaultPrng(), std::numeric_limits<Integral>::max());
}
/** @} */

/**
 * Return a random byte
 */
/** @{ */
template <class Byte, class Engine>
Byte
randByte(Engine& engine)
    requires(
        (std::is_same_v<Byte, unsigned char> || std::is_same_v<Byte, std::uint8_t>) &&
        detail::is_engine<Engine>::value)
{
    return static_cast<Byte>(randInt<Engine, std::uint32_t>(
        engine, std::numeric_limits<Byte>::min(), std::numeric_limits<Byte>::max()));
}

template <class Byte = std::uint8_t>
Byte
randByte()
    requires(std::is_same_v<Byte, unsigned char> || std::is_same_v<Byte, std::uint8_t>)
{
    return randByte<Byte>(defaultPrng());
}
/** @} */

/**
 * Return a random boolean value
 */
/** @{ */
template <class Engine>
inline bool
randBool(Engine& engine)
{
    return randInt(engine, 1) == 1;
}

inline bool
randBool()
{
    return randBool(defaultPrng());
}
/** @} */

}  // namespace xrpl