Define Callable functions

The callable function may verify the request comes from an authenticated user, perform work and send back a result or an error. It may stream the response.

Overview and syntax

synopsis

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

provide a callback

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

The callback receives the request object of type CallableRequest. Its main properties are auth and data. The callback also receives a response object that we may use to stream content.

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
• request's acceptsStreaming property indicates if we may stream the response.

The callback usually 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 options

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

Cloud functions patterns

halt and send an error immediately

We throw an HttpsError instance with specific error code string which follows a predefined list. If we don't provide a specific error, it defaults to an internal error.

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

lightweight file: dispatch work

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

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.

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