Feature: Callable Functions support

[MGatner]

Callable Functions add significant functionality to a Firebase project, relieving the developer from handling multiple services simultaneously. There appear to be two variants of Callable Functions: "HTTPS callable functions" and "HTTP functions" (this goes beyond simply the protocol used, see https://firebase.google.com/docs/functions/callable). The former (as far as I can tell) requires one of Google's SDKs:

Firebase SDK for iOS 6.13.0
Firebase SDK for Android 19.0.1
Firebase JavaScript SDK 7.5.2

But the latter can be implemented by following their protocol specification: https://firebase.google.com/docs/functions/callable-reference

I think this would be a great addition to firebase-php to allow native Cloud Function calls from the backend. See also #284

[MGatner]

After spending some more time on this I would like to clarify what was either my misunderstanding or an ambiguity in the docs (maybe both):

HTTPS callable functions are similar but not identical to HTTP functions

This is noting that "Firebase callable functions aren't your ordinary RESTful API" because they have a very precise protocol that must be followed. This reinforces my thought that this would be a good addition to this library, since the protocol is very specific to Firebase and won't be covered by any generic cURL wrappers.

[MGatner]

I have anonymous callable functions working with a simple cURL request, setting only the headers specified in the protocol:

$response = $client
	->setHeader('Content-Type', "application/json; charset=utf-8")
	->setBody(json_encode($data))
	->post($url, ['http_errors' => false]);

Note that lots of clients will magic set headers for you, but I had to specify them because it was always adding Content-Length which is not allowed.

When I add in the authenticated user token (->setHeader('Authorization', 'Bearer ' . $token->accessToken)) it gets rejected:

{"error":{"message":"Unauthenticated","status":"UNAUTHENTICATED"}}

I assume I'm using the wrong token or something... it's what I received back from FirebaseUI after a successful login.

[jeromegamez]

As you‘re already at it ^^, how did you create the client? If you use $factory->createApiClient(), the service account‘s credentials will be used for the Authorization header.

I haven‘t checked yet, but perhaps there‘s an additional OAuth2 scope needed to invoke cloud functions.

That would be a good test to see if a cloud functions must be invoked by a user explicitly or if the un“identified“ general service account is perhaps enough (I sincerely hope it does)

[jeromegamez]

If it doesn't work, another possibility could be to generate an ID Token for a user like in

firebase-php/tests/Integration/AuthTest.php

Lines 145 to 148 in 568a9a7

	$idTokenResponse = $this->auth->getApiClient()->exchangeCustomTokenForIdAndRefreshToken(
	$this->auth->createCustomToken($user->uid)
	);
	$idToken = JSON::decode((string) $idTokenResponse->getBody(), true)['idToken'];

and use that token for the authorization header. (Just thinking out loud 😅)

[MGatner]

Yes I think you are right that I am using the wrong token. I'm playing with this right now to get it from the frontend but then I will try your version as well:

firebase.auth().currentUser.getIdToken(/* forceRefresh */ true).then(function(idToken) {
  // Send token to your backend via HTTPS
  // ...
}).catch(function(error) {
  // Handle error
});

[MGatner]

if a cloud functions must be invoked by a user explicitly or if the un“identified“ general service account is perhaps enough

I was able to invoke the callable without any credentials at all, actually! It ran fine, I saw in the logs. The issue is that many of the callable functions use context.auth, with is based on the authentication header token and tied to an actual user. Certainly developers can write their callable functions however they like, but I think it is wise to require some authentication and for calls explicit to one user it makes sense to call it as that user.

EDIT: I should add that this behavior is more than just a whimsical developer choice, but matches the default SDK behavior for mobile since they will always include the current user token for callable functions.

[jeromegamez]

You can specify custom claims when generating the custom token with the SDK, do they perhaps get passed to the context.auth when set?

Another possibility, based on the code that you presented, and if I'm not misunderstanding/forgetting something, would be to send the ID token from firebase.auth().currentUser.getIdToken(/* forceRefresh */ true).then(function(idToken) {...} to the PHP backend and use that string for the Authorization: Bearer <value>, not the access token.

[MGatner]

That works! It's definitely a token type issue - not sure what FirebaseUI-Auth is returning in accessToken but it isn't a Firebase ID Token :)

The actual code is a mess but here's an example of pretty much what I did:

/** Firebase Callable Function
 *  Assumes $user->uid and $credentials and a cURL client
 */

$factory = (new Factory)->withServiceAccount($credentials);
$auth = $factory->createAuth();

$idTokenResponse = $auth->getApiClient()->exchangeCustomTokenForIdAndRefreshToken( 
	$auth->createCustomToken($user->uid) 
); 

$idToken = json_decode((string) $idTokenResponse->getBody(), true)['idToken']; 

$client = Services::curlrequest();
$url    = 'https://us-central1-myproject.cloudfunctions.net/myCallableFunction';
$body = [
	'data' => ['foo' => 'bar']
];

$response = $client
	->setHeader('Content-Type', "application/json; charset=utf-8")
	->setHeader('Authorization', 'Bearer ' . $idToken)
	->setBody(json_encode($body))
	->post($url, ['http_errors' => false]);

[jeromegamez]

Great work! That's something I could definitely work with!

Is the whole URL something that a developer would have to provide, or can it be somehow derived from some other information? What I'm meaning is... would you see more withers in the factory to provide a "cloud function region" and can the URL be constructed with something like https://{$region}-{$projectId}.cloudfunctions.net, or would you rather say: "if a developer has a cloud function they'd like to invoke, then providing the full URL is okay.

[MGatner]

As far as I know the cloud function subdomain will always match the Firebase project, like you said, so theoretically you could execute a cloud function call from the factory by simply passing it the name of the function and the data.

[jeromegamez]

I was wondering because of the us-central1- prefix... I imagine that this could differ from project to project... I'll have to test that on mine as well 😅

[MGatner]

I'm afraid my Firebase knowledge is limited that one project, with a test and production instance, so I can't really say!

[jeromegamez]

I will start with the new component as soon as I have released #360. looking forward to doing so 🥳

[MGatner]

Splendid! Let me know how I can help.

[jeromegamez]

Quick heads-up: I’m on it, but I’m going back and forth on how elaborate/configurable I want the implementation to be, so it might still take a while 😅

[MGatner]

That’s great! No worries on the timing. My implementation is working great. I thought I’d shared it (Discord maybe?) but here it is just in case: https://github.com/tattersoftware/codeigniter4-firebase/blob/develop/src/Components/Caller.php

Feel free to borrow without attribution as ultimately I will be using the version from this library and not maintaining my own.