Define Callable functions

The callable function checks authentication, triggers internal functions, and send back the result when it's available, and/or send back an error if the operation failed. It may stream the response.

Overview and syntax

synopsis

onCall<T, U, V>(options, callback)

provide a callback to onCall

onCall's main argument is the callback function that we define ourself. We define it async so it returns a promise.

The callback receives a request object as its main argument, of type CallableRequest. Its main properties are auth and data. The callback also receives a response object, which we may use to stream so chunks.

onCall<ReqData, Promise<ResData>, StreamData>(async (request, response) => {
    request.auth
    request.data // ReqData
    response?.sendChunk("abc") // StreamData is string here
    response?.sendChunk("def") // StreamData is string here
    return { example: "" }
})

• request.auth is of type AuthData | undefined. It is undefined when the request is unauthenticated. It has uid and token.email props.
• request.data's type is provided by the first type parameter in onCall<T,U,V>(), here ReqData

The callback returns an object, whose type is provided by the second parameter in onCall<T,U,V>(), here ResData

type example

interface ReqData {
    character: string
}
interface ResData {
    example: string
}
type StreamData = string

provide settings

we may give onCall an options argument object, of type CallableOptions, a subclass of GlobalOptions, as the first argument. Options include region, concurrency, minInstances and maxInstances.

Concurrency sets how many processes a single instance may run in parallel. By default, it may run multiple processes in parallel, even when there is a single instance. We may limit the number of process to one, so that there the server only runs a single process at time, aka process a single request at a time.

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

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")
}

Cloud function patterns and misc

halt and sends error to client

We provide a specific error code string which belongs to a predefined list. If we omit any argument, it defaults to an internal error.

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

lightweight endpoint: dispatch work

A callable function endpoint must delegate application logic to internal functions, in order to remain a lightweight and readable function.

run side effects, return data

the callable function performs side effects and/or returns some data.

endpoint naming: requestX

using request indicates the server may refuse to perform the action. It separates the request from the action proper. The action proper may be performed by an internal function.

we may call the endpoint requestVerb, and the internal function verb or performVerb.

For example, requestCreateFleetMission calls the createFleetMission internal function.