remote.h

Go to the documentation of this file.

#pragma once
 
#include "fl/stl/json.h"
#include "fl/stl/stdint.h"
#include "fl/stl/cstddef.h"
#include "fl/stl/move.h"
#include "fl/stl/string.h"
#include "fl/system/sketch_macros.h"  // FL_PLATFORM_HAS_LARGE_MEMORY -- gates RAM fields
#include "fl/stl/unordered_map.h"
#include "fl/stl/vector.h"
#include "fl/stl/strstream.h"  // IWYU pragma: keep
#include "fl/remote/rpc/rpc.h"
#include "fl/remote/rpc/rpc_mode.h"
#include "fl/remote/rpc/response_stream.h"
#include "fl/remote/rpc/server.h"
#include "fl/remote/types.h"
#include "fl/net/rpc_scheduler.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
// Forward declarations
class ResponseSend;

class Remote : public Server {
public:
    template<typename Callable>
    using Config = typename fl::Rpc::Config<Callable>;
 
    // Import types from various sources
    using RpcResult = fl::RpcResult;      // from fl/remote/types.h
    using ClearFlags = fl::RemoteClearFlags;    // from fl/remote/types.h
    using MethodInfo = fl::MethodInfo;    // from fl/remote/rpc/rpc.h
    using ParamInfo = fl::ParamInfo;      // from fl/remote/rpc/rpc.h

    Remote(RequestSource source, ResponseSink sink) FL_NO_EXCEPT;

    Remote(RequestSource source, ResponseSink sink, ResponseStreamSink streamSink) FL_NO_EXCEPT;
 
    // Non-copyable, non-movable (lambda captures 'this')
    Remote(const Remote&) FL_NO_EXCEPT = delete;
    Remote(Remote&&) FL_NO_EXCEPT = delete;
    Remote& operator=(const Remote&) FL_NO_EXCEPT = delete;
    Remote& operator=(Remote&&) FL_NO_EXCEPT = delete;
 
    // =========================================================================
    // Method Registration
    // =========================================================================

    template<typename Callable>
    void bind(const Config<Callable>& config) FL_NO_EXCEPT {
        mRpc.bind(config);
    }

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

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

    void bindStreaming(const char* name, fl::StreamingRpcHandler fn) FL_NO_EXCEPT {
        mRpc.bindStreaming(name, fl::move(fn));
    }

    template<class Sig>
    fl::BindResult<Sig> get(const char* name) const FL_NO_EXCEPT {
        return mRpc.get<Sig>(name);
    }

    bool has(const fl::string& name) const FL_NO_EXCEPT;

    bool unbind(const fl::string& name) FL_NO_EXCEPT;
 
    // =========================================================================
    // RPC Processing
    // =========================================================================

    fl::json processRpc(const fl::json& request) FL_NO_EXCEPT;
 
    // =========================================================================
    // Server Coordination
    // =========================================================================

    size_t update(u32 currentTimeMs) FL_NO_EXCEPT;

    size_t tick(u32 currentTimeMs) FL_NO_EXCEPT;
 
    // Note: pull() and push() inherited from Server<fl::json, fl::json>
 
    // =========================================================================
    // Results and State
    // =========================================================================

    size_t pendingCount() const FL_NO_EXCEPT;

    void clear(ClearFlags flags) FL_NO_EXCEPT;
 
    // =========================================================================
    // Schema
    // =========================================================================

    fl::vector<MethodInfo> methods() const FL_NO_EXCEPT;

    fl::json schema() const FL_NO_EXCEPT {
        return mRpc.schema();
    }

    fl::size count() const FL_NO_EXCEPT {
        return mRpc.count();
    }
 
    // =========================================================================
    // Async Response Support
    // =========================================================================

    void sendAsyncResponse(const char* method, const fl::json& result) FL_NO_EXCEPT;

    void sendStreamUpdate(const char* method, const fl::json& update) FL_NO_EXCEPT;

    void sendStreamFinal(const char* method, const fl::json& result) FL_NO_EXCEPT;
 
    // =========================================================================
    // Error Reporting (Unsolicited Notifications)
    // =========================================================================

    void reportError(const fl::string& message) FL_NO_EXCEPT;

    void reportError(const fl::json& data) FL_NO_EXCEPT;
 
protected:
    // Storage for async request IDs (method name -> request ID).
    // Gated on Low-memory per #3224 Tier 1B: the LowMemory async-tracking +
    // scheduling + result-vector paths are all `#if`'d out of processRpc, so
    // the corresponding instance state is dead RAM weight. Drop the field
    // declarations entirely on Low-memory to recover several hundred bytes
    // of .bss per Remote instance.
    struct AsyncRequest {
        int requestId;
        u32 timestamp;
    };
#if FL_PLATFORM_HAS_LARGE_MEMORY
    fl::unordered_map<fl::string, AsyncRequest> mAsyncRequests;
    void scheduleFunction(u32 timestamp, u32 receivedAt, const fl::json& jsonRpcRequest) FL_NO_EXCEPT;
    void recordResult(const fl::string& funcName, const fl::json& result, u32 scheduledAt, u32 receivedAt, u32 executedAt, bool wasScheduled) FL_NO_EXCEPT;
#endif
 
    // Method registry and execution
    fl::Rpc mRpc;
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
    // Generic task scheduler
    fl::net::RpcScheduler<> mScheduler;
 
    // RPC-specific result tracking
    fl::vector<RpcResult> mResults;
#endif
 
    // Note: mRequestSource, mResponseSink, mOutgoingQueue inherited from Server
};
 
} // namespace fl