rpc.h

Go to the documentation of this file.

#pragma once
 
#include "fl/stl/json.h"  // IWYU pragma: keep
 
// =============================================================================
// RPC System - Main Public API
// =============================================================================
//
// This header provides the complete typed RPC system for FastLED.
//
// PUBLIC API:
//   - fl::Rpc          : Main RPC registry class
//   - fl::RpcHandle<S> : Callable handle returned from method() registration
//
// EXAMPLE USAGE:
//
//   #include "fl/remote/rpc/rpc.h"
//
//   fl::Rpc rpc;
//
//   // Bind (register) method - simple (constructor style)
//   rpc.bind(Rpc::Config{"add", [](int a, int b) { return a + b; }});
//
//   // Bind method - simple (designated initializer style)
//   rpc.bind({.name = "add", .fn = [](int a, int b) { return a + b; }});
//
//   // With metadata - designated initializer style
//   rpc.bind({
//       .name = "multiply",
//       .fn = [](int a, int b) { return a * b; },
//       .params = {"a", "b"},
//       .description = "Multiplies two integers",
//       .tags = {"math"}
//   });
//
//   // With metadata - constructor style
//   rpc.bind(Rpc::Config{
//       "divide",                             // name
//       [](int a, int b) { return a / b; },   // function
//       {"dividend", "divisor"},              // params
//       "Divides two integers"                // description
//   });
//
//   // Group methods using dot notation for namespacing:
//   rpc.bind({"led.setBrightness", [](int b) { /* ... */ }});
//   rpc.bind({"led.setColor", [](int r, int g, int b) { /* ... */ }});
//   rpc.bind({"system.status", []() -> fl::string { return "ok"; }});
//
//   // Get by name and call later
//   auto addFn = rpc.get<int(int, int)>("add");
//   if (addFn) {  // Check if binding succeeded
//       int sum = addFn(5, 7);  // Call directly!
//   } else if (addFn.error() == fl::BindError::NotFound) {
//       // Method not registered
//   } else {  // fl::BindError::SignatureMismatch
//       // Method exists but signature doesn't match
//   }
//
//   // JSON-RPC transport
//   fl::json request = fl::json::parse(R"({"method":"add","params":[6,7],"id":1})");
//   fl::json response = rpc.handle(request);
//
//   // Schema generation (flat tuple format) - always available
//   fl::json schema = rpc.schema();      // Flat schema document
//   fl::json methods = rpc.methods();    // Flat method array
//
//   // Built-in rpc.discover method (always available)
//   fl::json request = fl::json::parse(R"({"method":"rpc.discover","id":1})");
//   fl::json response = rpc.handle(request);  // Returns flat schema
//
// =============================================================================
 
#include "fl/stl/json.h"  // IWYU pragma: keep
// Internal RPC headers
#include "fl/remote/rpc/rpc_handle.h"
#include "fl/remote/rpc/rpc_registry.h"
#include "fl/remote/rpc/rpc_mode.h"
#include "fl/remote/rpc/response_stream.h"
#include "fl/remote/rpc/runtime_rpc_binding.h"  // RuntimeRpcBinding (low-memory dispatch, #3246)
#include "fl/system/sketch_macros.h"             // FL_PLATFORM_HAS_LARGE_MEMORY
 
// STL headers required for public API
#include "fl/stl/stdint.h"
#include "fl/stl/string.h"
#include "fl/stl/vector.h"
#include "fl/stl/optional.h"
#include "fl/stl/expected.h"
#include "fl/stl/function.h"
#include "fl/stl/unordered_map.h"
#include "fl/stl/type_traits.h"
#include "fl/stl/initializer_list.h"  // IWYU pragma: keep
#include "fl/stl/noexcept.h"
 
namespace fl {
 
// Forward declarations
class ResponseSend;
 
// =============================================================================
// BindError - Error codes for bind() failures
// =============================================================================
 
enum class BindError {
    NotFound,          // No method registered with that name
    SignatureMismatch  // Method exists but signature doesn't match
};
 
// =============================================================================
// RPC Schema Types
// =============================================================================

struct ParamInfo {
    fl::string name;
    fl::string type;
};

struct MethodInfo {
    fl::string name;
    fl::vector<ParamInfo> params;
    fl::string returnType;
    fl::string description;
    fl::vector<fl::string> tags;
};
 
// =============================================================================
// BindResult - Result wrapper for bind() operations
// =============================================================================

template<typename Sig>
struct BindResult;
 
template<typename R, typename... Args>
struct BindResult<R(Args...)> {
    fl::expected<RpcFn<R(Args...)>, BindError> inner;

    BindResult(fl::expected<RpcFn<R(Args...)>, BindError> exp) FL_NO_EXCEPT : inner(fl::move(exp)) {}

    BindResult(RpcFn<R(Args...)> fn) FL_NO_EXCEPT : inner(fl::expected<RpcFn<R(Args...)>, BindError>::success(fl::move(fn))) {}

    bool has_value() const FL_NO_EXCEPT { return inner.has_value(); }
    bool ok() const FL_NO_EXCEPT { return inner.has_value(); }
    explicit operator bool() const FL_NO_EXCEPT { return inner.has_value(); }

    RpcFn<R(Args...)> value() const FL_NO_EXCEPT { return inner.value(); }
    RpcFn<R(Args...)>& value() FL_NO_EXCEPT { return inner.value(); }

    BindError error() const FL_NO_EXCEPT { return inner.error(); }

    const fl::expected<RpcFn<R(Args...)>, BindError>& get() const FL_NO_EXCEPT { return inner; }

    R operator()(Args... args) const FL_NO_EXCEPT {
        return inner.value()(fl::forward<Args>(args)...);
    }
};
 
// =============================================================================
// Rpc - Main typed RPC registry
// =============================================================================
//
// The primary class for registering and invoking RPC methods.
// Methods can be registered with auto-deduced signatures and called either
// directly (via RpcHandle), by binding, or through JSON-RPC transport.
 
class Rpc {
public:
    template<typename Callable>
    struct Config {
        fl::string name;                            
        Callable fn;                                
        fl::RpcMode mode = fl::RpcMode::SYNC;       
        fl::vector<fl::string> params = {};         
        fl::string description = "";                
        fl::vector<fl::string> tags = {};           

        Config(fl::string n, Callable f, fl::RpcMode m = fl::RpcMode::SYNC)
            FL_NO_EXCEPT : name(fl::move(n)), fn(fl::move(f)), mode(m) {}

        Config(fl::string n, Callable f, fl::vector<fl::string> p, fl::RpcMode m = fl::RpcMode::SYNC)
            FL_NO_EXCEPT : name(fl::move(n)), fn(fl::move(f)), mode(m), params(fl::move(p)) {}

        Config(fl::string n,
               Callable f,
               fl::vector<fl::string> p,
               fl::string desc,
               fl::vector<fl::string> t = {},
               fl::RpcMode m = fl::RpcMode::SYNC)
            FL_NO_EXCEPT : name(fl::move(n)), fn(fl::move(f)), mode(m), params(fl::move(p)),
              description(fl::move(desc)), tags(fl::move(t)) {}
    };
 
    Rpc() FL_NO_EXCEPT = default;
    ~Rpc() FL_NO_EXCEPT = default;
 
    // Non-copyable but movable
    Rpc(const Rpc&) FL_NO_EXCEPT = delete;
    Rpc& operator=(const Rpc&) FL_NO_EXCEPT = delete;
    Rpc(Rpc&&) FL_NO_EXCEPT = default;
    Rpc& operator=(Rpc&&) FL_NO_EXCEPT = default;
 
    // =========================================================================
    // Response Sink for Async ACKs
    // =========================================================================

    void setResponseSink(fl::function<void(const fl::json&)> sink) FL_NO_EXCEPT;

    void setResponseStreamSink(fl::ResponseStreamSink sink) FL_NO_EXCEPT;

    void setResponseStreamAvailable(fl::function<bool()> available) FL_NO_EXCEPT;
 
    // =========================================================================
    // Method Registration (Binding)
    // =========================================================================

    template<typename Callable>
    void bind(const Config<Callable>& config) FL_NO_EXCEPT {
        using Sig = typename callable_traits<typename decay<Callable>::type>::signature;
        RpcFn<Sig> wrapped(config.fn);
        registerMethod<Sig>(config.name.c_str(), wrapped, config.params, config.description, config.tags, config.mode);
    }

    template<typename Callable>
    void bind(const char* name, Callable fn, fl::RpcMode mode = fl::RpcMode::SYNC) FL_NO_EXCEPT {
        bind(Config<Callable>{name, fl::move(fn), mode});
    }

    void bindAsync(const char* name,
                   fl::function<void(ResponseSend&, const json&)> fn,
                   fl::RpcMode mode = fl::RpcMode::ASYNC) FL_NO_EXCEPT;

    void bindStreaming(const char* name, fl::StreamingRpcHandler fn) FL_NO_EXCEPT;
 
    // =========================================================================
    // Method Retrieval
    // =========================================================================

    template<class Sig>
    BindResult<Sig> get(const char* name) const FL_NO_EXCEPT {
        fl::string key(name);
        auto it = mRegistry.find(key);
        if (it == mRegistry.end()) {
            return BindResult<Sig>(fl::expected<RpcFn<Sig>, BindError>::failure(BindError::NotFound));
        }
        if (it->second.mTypeTag != detail::TypeTag<Sig>::id()) {
            return BindResult<Sig>(fl::expected<RpcFn<Sig>, BindError>::failure(BindError::SignatureMismatch));
        }
        auto* holder = static_cast<detail::TypedCallableHolder<Sig>*>(
            it->second.mTypedCallable.get());
        if (!holder) {
            return BindResult<Sig>(fl::expected<RpcFn<Sig>, BindError>::failure(BindError::NotFound));
        }
        return BindResult<Sig>(holder->mFn);
    }

    bool has(const char* name) const FL_NO_EXCEPT {
        return mRegistry.find(fl::string(name)) != mRegistry.end();
    }

    bool unbind(const char* name) FL_NO_EXCEPT {
        fl::string key(name);
        auto it = mRegistry.find(key);
        if (it != mRegistry.end()) {
            mRegistry.erase(it);
            return true;
        }
        return false;
    }

    void clear() FL_NO_EXCEPT {
        mRegistry.clear();
    }
 
    // =========================================================================
    // JSON-RPC Transport
    // =========================================================================

    json handle(const json& request) FL_NO_EXCEPT;

    fl::optional<json> handle_maybe(const json& request) FL_NO_EXCEPT;
 
    // =========================================================================
    // Schema and Discovery
    // =========================================================================

    json methods() const FL_NO_EXCEPT;

    json schema() const FL_NO_EXCEPT;
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
    void writeSchema(fl::JsonStreamWriter& writer) const FL_NO_EXCEPT;
#endif

    fl::size count() const FL_NO_EXCEPT {
        return mRegistry.size();
    }

    fl::vector<fl::string> tags() const FL_NO_EXCEPT;
 
    // =========================================================================
    // Internal Registration (used by MethodBuilder)
    // =========================================================================
 
    template<class Sig>
    bool registerMethod(const char* name, RpcFn<Sig> fn,
                        const fl::vector<fl::string>& paramNames,
                        const fl::string& description,
                        const fl::vector<fl::string>& tags,
                        fl::RpcMode mode = fl::RpcMode::SYNC) FL_NO_EXCEPT {
        fl::string key(name);
        auto it = mRegistry.find(key);
        if (it != mRegistry.end()) {
            if (it->second.mTypeTag != detail::TypeTag<Sig>::id()) {
                return false;
            }
        }
 
        detail::RpcEntry entry;
        entry.mTypeTag = detail::TypeTag<Sig>::id();
        // Per-Sig dispatch fork (FastLED #3246). Low-memory targets pay only
        // a ~50-150 B trampoline per signature via RuntimeRpcBinding instead
        // of the ~2.1 KB TypedRpcBinding<Sig>::invokeWithReturn instantiation.
        // Large-memory targets keep the existing fast inline-dispatch path.
#if FL_PLATFORM_HAS_LARGE_MEMORY
        entry.mInvoker = fl::make_shared<detail::TypedInvoker<Sig>>(fn);
#else
        entry.mInvoker = detail::makeRuntimeRpcBinding(fn);
#endif
        entry.mTypedCallable = fl::make_shared<detail::TypedCallableHolder<Sig>>(fn);
#if FL_PLATFORM_HAS_LARGE_MEMORY
        // Schema generator construction gated on Low-memory targets per
        // FastLED #3081 / #3079. The schema generator is only consumed by
        // `rpc.discover` (also gated). Skipping it on Low-memory drops
        // `TypedSchemaGenerator<Sig>::params()` (~800 B per signature).
        entry.mSchemaGenerator = fl::make_shared<detail::TypedSchemaGenerator<Sig>>();
#endif
        entry.mDescription = description;
        entry.mTags = tags;
        entry.mMode = mode;
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
        if (!paramNames.empty()) {
            entry.mSchemaGenerator->setParamNames(paramNames);
        }
#else
        (void)paramNames;
#endif
 
        mRegistry[key] = fl::move(entry);
        return true;
    }
 
private:
    fl::unordered_map<fl::string, detail::RpcEntry> mRegistry;
    fl::function<void(const fl::json&)> mResponseSink;  // For sending ACK responses
#if FL_PLATFORM_HAS_LARGE_MEMORY
    fl::ResponseStreamSink mResponseStreamSink;
    fl::function<bool()> mResponseStreamAvailable;
#endif
};
 
// RpcFactory is kept as an alias for backwards compatibility
using RpcFactory = Rpc;
 
} // namespace fl