handle()

json fl::Rpc::handle

(

const json &

request

)

Process a JSON-RPC request.

Request format: {"method": "name", "params": [...], "id": ...} Response format: {"result": ..., "id": ...} or {"error": {...}, "id": ...}

Definition at line 134 of file rpc.cpp.hpp.

                                                 {
    // Extract method name
    if (!request.contains("method")) {
        FL_ERROR("RPC: Invalid Request - missing 'method' field");
        return detail::makeJsonRpcError(-32600, FL_RPC_ERR_NO_METHOD, request["id"]);
    }
 
    auto methodOpt = request["method"].as_string();
    if (!methodOpt.has_value()) {
        FL_ERROR("RPC: Invalid Request - 'method' must be a string");
        return detail::makeJsonRpcError(-32600, FL_RPC_ERR_METHOD_NOT_STR, request["id"]);
    }
    fl::string methodName = methodOpt.value();
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
    // Handle built-in rpc.discover method. Gated on Low-memory targets because
    // it transitively anchors `TypedSchemaGenerator<Sig>::params()` for every
    // registered method (each 800+ B per signature) plus the schema-building
    // JSON tree. The LPC8xx / AVR-class JSON-RPC bring-up surface treats the
    // RPC catalog as a known constant -- callers don't introspect at runtime.
    // See FastLED #3081.
    if (methodName == "rpc.discover") {
        // Stream when possible: the schema tree for a large registry can
        // exceed the free heap on ESP32-S3 (FastLED #4899). Scheduled calls
        // (non-zero timestamp) keep the inline result so it is recorded.
        // Stream sinks run the callback synchronously, so `self` outlives it.
        const bool scheduled = request.contains("timestamp") &&
                               request["timestamp"].as_int().value_or(0) != 0;
        if (!scheduled && mResponseStreamSink &&
            (!mResponseStreamAvailable || mResponseStreamAvailable())) {
            fl::json requestId = request.contains("id") ? request["id"] : json(nullptr);
            const bool includeId = request.contains("id");
            const Rpc* self = this;
            mResponseStreamSink([self, requestId, includeId](fl::JsonStreamWriter& writer) {
                streamJsonRpcResultEnvelope(
                    writer, requestId, includeId,
                    [self](fl::JsonStreamWriter& resultWriter) {
                        self->writeSchema(resultWriter);
                    });
            });
            fl::json skip = fl::json::object();
            skip.set("noEnqueue", true);
            return skip;
        }
        json response = json::object();
        response.set("jsonrpc", "2.0");
        response.set("result", schema());
        if (request.contains("id")) {
            response.set("id", request["id"]);
        }
        return response;
    }
#endif
 
    // Look up the method
    auto it = mRegistry.find(methodName);
    if (it == mRegistry.end()) {
        FL_WARN("RPC: Method not found: " << methodName.c_str());
        return detail::makeJsonRpcError(-32601, fl::string(FL_RPC_ERR_METHOD_NOT_FOUND_PREFIX) + methodName, request["id"]);
    }
 
    // Extract params (default to empty array)
    json params = request.contains("params") ? request["params"] : json::parse("[]");
    if (!params.is_array()) {
        FL_ERROR("RPC: Invalid params - must be an array for method: " << methodName.c_str());
        return detail::makeJsonRpcError(-32602, FL_RPC_ERR_PARAMS_NOT_ARRAY, request["id"]);
    }
 
    // Check if this is an async function
    const detail::RpcEntry& entry = it->second;
#if FL_PLATFORM_HAS_LARGE_MEMORY
    if (entry.mIsStreaming) {
        if (!mResponseStreamSink) {
            return detail::makeJsonRpcError(-32603, "Streaming response sink not configured", request["id"]);
        }
 
        fl::StreamingRpcHandler streamFn = entry.mStreamingFn;
        fl::json paramsCopy = params;
        fl::json requestId = request.contains("id") ? request["id"] : json(nullptr);
        const bool includeId = request.contains("id");
        mResponseStreamSink([streamFn, paramsCopy, requestId, includeId](fl::JsonStreamWriter& writer) {
            streamJsonRpcResultEnvelope(
                writer,
                requestId,
                includeId,
                [streamFn, paramsCopy, requestId](fl::JsonStreamWriter& resultWriter) {
                    if (streamFn) {
                        streamFn(resultWriter, paramsCopy, requestId);
                    } else {
                        resultWriter.valueNull();
                    }
                });
        });
 
        fl::json skip = fl::json::object();
        skip.set("noEnqueue", true);
        return skip;
    }
 
    bool isAsync = (entry.mMode == RpcMode::ASYNC || entry.mMode == RpcMode::ASYNC_STREAM);
 
    // Check if this is a response-aware function (uses ResponseSend&)
    bool isResponseAware = entry.mIsResponseAware;
 
    // For async functions, send ACK immediately
    if (isAsync && mResponseSink && request.contains("id")) {
        json ack = json::object();
        ack.set("jsonrpc", "2.0");
        ack.set("id", request["id"]);
 
        json ackResult = json::object();
        ackResult.set("acknowledged", true);
        ack.set("result", ackResult);
 
        mResponseSink(ack);
        FL_DBG("RPC: Sent ACK for async method: " << methodName.c_str());
    }
#endif
 
    fl::tuple<TypeConversionResult, json> resultTuple;
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
    // Handle response-aware methods (with ResponseSend& parameter)
    if (isResponseAware) {
        // Create ResponseSend instance
        fl::json requestId = request.contains("id") ? request["id"] : json(nullptr);
        ResponseSend responseSend(requestId, mResponseSink);
 
        // Invoke user function with ResponseSend& and raw JSON params
        entry.mResponseAwareFn(responseSend, params);
 
        // Return success with null result (actual responses sent via ResponseSend)
        resultTuple = fl::make_tuple(TypeConversionResult::success(), json(nullptr));
    } else {
        // Regular invocation
        resultTuple = entry.mInvoker->invoke(params);
    }
#else
    // Low-memory targets only register regular (non-response-aware) sync RPCs;
    // the bindAsync path is gated out (see #3224 Tier 1B). Drop the
    // isResponseAware branch entirely to slim Rpc::handle.
    resultTuple = entry.mInvoker->invoke(params);
#endif
 
    TypeConversionResult convResult = fl::get<0>(resultTuple);
    json returnVal = fl::get<1>(resultTuple);
 
    // Check for conversion errors
    if (!convResult.ok()) {
        FL_ERROR("RPC: Invalid params for method '" << methodName.c_str() << "': " << convResult.errorMessage().c_str());
        return detail::makeJsonRpcError(-32602, fl::string(FL_RPC_ERR_INVALID_PARAMS_PREFIX) + convResult.errorMessage(), request["id"]);
    }
 
    // Build success response
    json response = json::object();
    response.set("jsonrpc", "2.0");
    response.set("result", returnVal);
 
    // Include id if present (for request/response correlation)
    if (request.contains("id")) {
        response.set("id", request["id"]);
    }
 
#if FL_PLATFORM_HAS_LARGE_MEMORY
    // Include warnings if any. Low-memory targets emit warnings only as
    // explicit error returns (e.g. our gated `float -> int not supported`
    // path in #3224 Tier 1A) -- the warnings-array variant emplace + nested
    // json::array() builder + push_back path was a measurable contributor
    // to the LowMemory .text mass on its own.
    if (convResult.hasWarning()) {
        json warnings = json::array();
        for (fl::size i = 0; i < convResult.warnings().size(); ++i) {
            warnings.push_back(json(convResult.warnings()[i]));
        }
        response.set("warnings", warnings);
    }
 
    // For async functions, mark response to signal "ACK already sent" so
    // downstream queue machinery skips pushing a duplicate response.
    // Renamed from `__async` in #3228 -- field is a public envelope-control
    // marker, not a reserved-namespace identifier.
    if (isAsync) {
        response.set("ackOnly", true);
    }
#endif
 
    return response;
}

References Rpc(), fl::json::array(), fl::ASYNC, fl::ASYNC_STREAM, fl::basic_string::c_str(), fl::json::contains(), fl::TypeConversionResult::errorMessage(), FL_DBG, FL_ERROR, fl::FL_NO_EXCEPT, FL_RPC_ERR_INVALID_PARAMS_PREFIX, FL_RPC_ERR_METHOD_NOT_FOUND_PREFIX, FL_RPC_ERR_METHOD_NOT_STR, FL_RPC_ERR_NO_METHOD, FL_RPC_ERR_PARAMS_NOT_ARRAY, FL_WARN, fl::get(), fl::TypeConversionResult::hasWarning(), fl::json::is_array(), fl::adl_barrier::make_tuple(), fl::detail::makeJsonRpcError(), fl::detail::RpcEntry::mInvoker, fl::detail::RpcEntry::mIsResponseAware, fl::detail::RpcEntry::mMode, mRegistry, fl::detail::RpcEntry::mResponseAwareFn, mResponseSink, fl::json::object(), fl::TypeConversionResult::ok(), fl::json::parse(), fl::json::push_back(), requestId, schema(), fl::json::set(), fl::streamJsonRpcResultEnvelope(), fl::TypeConversionResult::success(), fl::JsonStreamWriter::valueNull(), and fl::TypeConversionResult::warnings().

Referenced by handle_maybe().

Here is the call graph for this function:

Here is the caller graph for this function: