Define Callable functions

The code we run in a Callable function has access to the user authentication status and the request's data.

Callable functions support streaming the response: we describe it in a dedicated section.

Overview and syntax

synopsis

onCall<ReqData, Promise<ResData>>(callback)
onCall<ReqData, Promise<ResData>>(options, callback)

the callback

The callback has access to the request (CallableRequest), which exposes auth and data.

We define the callback async so it returns a promise. The connection is kept open until the promise settles.

onCall<ReqData, Promise<ResData>>(async (request) => {
    request.auth // AuthData | undefined
    request.auth?.uid

    request.data // ReqData

    return { message: ".." } // ResData
})

• auth is undefined when the request is unauthenticated. It has uid otherwise.
• ReqData defines the data sent by clients.
• ResData defines what the callback returns.

set options

onCall accepts an optional options object, of type CallableOptions, a subclass of GlobalOptions, as the first argument.

const options: CallableOptions = {
    concurrency: 1, // how many
    minInstances: 1,
    maxInstances: 1,
    region: "europe-west1",
}

concurrency sets how many request a single instance may process in parallel. By default, a single instance processes multiple requests in parallel. We set it to one if we prefer sequential request processing, assuming we also set maxInstances to 1.

minInstances default to 0. To avoid cold starts, we can set minInstances to 1 but it costs more as it is warm all the time.

Streaming version

The request has acceptsStreaming, which we read to check if the client supports streaming. When it does, the callback has access to a response argument, on which we call response.sendChunk().

Streaming the response means to send small chunks of data with sendChunk().

The third type argument defines what kind of chunk we stream. We usually stream string chunks.

onCall<T, U, V>(options, callback) // streaming Callable

onCall<ReqData, Promise<ResData>, StreamData>(async (request, response) => {
    response?.sendChunk("abc") // StreamData
    response?.sendChunk("def")

    return { message: ".." } // fallback
})

Patterns

halt and send an error immediately

We throw an HttpsError instance with a specific error code string which conforms to a predefined list. If we omit the error code, it defaults to an internal error kind of error.

throw new HttpsError("unauthenticated", "unauthenticated")

endpoint naming: request + action

using request denotes that the server may refuse to perform the action. It separates the request from the action proper, which may live in another file.

logger

todo

Callable v1 (deprecated)

define the function

functions.https.onCall(async (data, context) => {
    const auth = context.auth
    const message = data.message
    return { message: ".." }
})

the context object

The context object provides the authentication details, if any, such as the email, and the request metadata such as the IP address, or the raw HTTP request. It is of type CallableContext

check authentication

if (!context.auth) {
    throw functions.https.HttpsError("unauthenticated", "you must be authenticated")
}