What should I return in an https callable function if it doesn't expect to return nothing

Question

I have implemented a HTTPs (onCall) function that throws some errors to the client or return true if the work is successfully completed. The problem is that I don't see why to return true (because when I throw the errors I don't return false).

As HTTP protocol requires to return a response to the client to finish a request, what should I return to the client? I am thinking to remove the errors I throw and return a classic HTTP reponse (status code, body, ...).

Any ideas? Here is what I am doing:

exports.function = functions
  .region("us-central1")
  .runWith({ memory: "2GB", timeoutSeconds: 120 })
  .https.onCall(async (data, context) => {

        // Lazy initialization of the Admin SDK
        if (!is_function_initialized) {
          // ... stuff
          is_uploadImage_initialized = true;
        }
    
        // ... asynchronous stuff
    
        // When all promises has been resolved...
        // If work completed successfully
        return true;
    
       /*
         Is it correct instead ???
         return {code: "200 OK", date: date, body: message };
       */
    
    
       // Else, if errors
       throw new Error("Please, try again later.");
    
       /*
         Is it correct instead ???
         return {code: "418 I'm a teapot", date: date, body: message };
       */

   }

Answer 1

As explained in the doc:

To use HTTPS Callable Functions you must use the client SDK for your platform together with the functions.https backend API (or implement the protocol)

which means that you must follow the protocol in any case, since the Client SDKs do implement the protocol.

So let's look at what says the protocol about the response to be sent to the client (i.e. the caller or consumer):

The protocol specifies the format of the Response Body as follows:

The response from a client endpoint is always a JSON object. At a minimum it contains either data or error, along with any optional fields. If the response is not a JSON object, or does not contain data or error, the client SDK should treat the request as failed with Google error code INTERNAL .

error - ....

data - The value returned by the function. This can be any valid JSON value. The firebase-functions SDK automatically encodes the value returned by the user into this JSON format. The client SDKs automatically decode these params into native types according to the serialization format described below.

If other fields are present, they should be ignored.

So, to answer to your question "what should I return to the client?", you should return data that can be JSON encoded. See also this section of the protocol doc.

---

For example, as detailed in the doc, in a Callable Cloud you can do

return {
  firstNumber: firstNumber,
  secondNumber: secondNumber,
  operator: '+',
  operationResult: firstNumber + secondNumber,
};
//Excerpt of the doc

or, you can do

return {result: "success"}

In your specific case ("What should I return in an https callable function if it doesn't expect to return nothing") you could very well return the following, as you mentioned in your question:

const date = new Date();
const message = "the message";

return { code: "200 OK", date: date, body: message };

But you could also do return true; or return null;... It's somehow up to you to decide what makes sense in your context.

---

Note that in the case you return { code: "200 OK", date: date, body: message } the value of code will not be considered, by the client, as an HTTP Response code, since this JSON object is injected in the Response body.