[ServerApp] Firebase Server App feature branch

common/api-review/app.api.md

@@ -71,6 +71,20 @@ export interface FirebaseOptions {
     storageBucket?: string;
 }
 
+// @public
+export interface FirebaseServerApp extends FirebaseApp {
+    authIdTokenVerified: () => Promise<void>;
+    name: string;
+    readonly settings: FirebaseServerAppSettings;
+}
+
+// @public
+export interface FirebaseServerAppSettings extends FirebaseAppSettings {
+    authIdToken?: string;
+    name?: undefined;
+    releaseOnDeref?: object;
+}
+
 // @internal (undocumented)
 export interface _FirebaseService {
     // (undocumented)
@@ -96,6 +110,15 @@ export function initializeApp(options: FirebaseOptions, config?: FirebaseAppSett
 // @public
 export function initializeApp(): FirebaseApp;
 
+// @public
+export function initializeServerApp(options: FirebaseOptions | FirebaseApp, config: FirebaseServerAppSettings): FirebaseServerApp;
+
+// @internal (undocumented)
+export function _isFirebaseApp(obj: FirebaseApp | FirebaseOptions): obj is FirebaseApp;
+
+// @internal (undocumented)
+export function _isFirebaseServerApp(obj: FirebaseApp | FirebaseServerApp): obj is FirebaseServerApp;
+
 // @public
 export function onLog(logCallback: LogCallback | null, options?: LogOptions): void;
 
@@ -111,6 +134,9 @@ export function _removeServiceInstance<T extends Name>(app: FirebaseApp, name: T
 // @public
 export const SDK_VERSION: string;
 
+// @public (undocumented)
+export const _serverApps: Map<string, FirebaseServerApp>;
+
 // @public
 export function setLogLevel(logLevel: LogLevelString): void;
 

config/tsconfig.base.json

@@ -15,6 +15,7 @@
       "es2015.core",
       "es2017.object",
       "es2017.string",
+      "ESNext.WeakRef",
     ],
     "module": "ES2015",
     "moduleResolution": "node",

docs-devsite/app.firebaseserverapp.md

@@ -0,0 +1,74 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# FirebaseServerApp interface
+A [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface) holds the initialization information for a collection of services running in server enviornments.
+
+Do not call this constructor directly. Instead, use [initializeServerApp()](./app.md#initializeserverapp_30ab697) to create an app.
+
+<b>Signature:</b>
+
+```typescript
+export interface FirebaseServerApp extends FirebaseApp 
+```
+<b>Extends:</b> [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [authIdTokenVerified](./app.firebaseserverapp.md#firebaseserverappauthidtokenverified) | () =&gt; Promise&lt;void&gt; | Checks to see if the local verification of the authIdToken provided to [initializeServerApp()](./app.md#initializeserverapp_30ab697) has completed.<!-- -->It is recommend that your application awaits this promise before invoking getAuth() if an authIdToken was provided in the FirebaseServerAppSettings.<!-- -->The returned Promise is completed immediately if the optional authIdToken parameter was omitted from FirebaseServerApp initialization. |
+|  [name](./app.firebaseserverapp.md#firebaseserverappname) | string | There is no getApp operation for FirebaseServerApps, so the name is not relevant for applications. However, it may be used internally, and is declared here so that FirebaseServerApp conforms to the FirebaseApp interface declaration. |
+|  [settings](./app.firebaseserverapp.md#firebaseserverappsettings) | [FirebaseServerAppSettings](./app.firebaseserverappsettings.md#firebaseserverappsettings_interface) | The (read-only) configuration settings for this server app. These are the original parameters given in [initializeServerApp()](./app.md#initializeserverapp_30ab697)<!-- -->. |
+
+## FirebaseServerApp.authIdTokenVerified
+
+Checks to see if the local verification of the authIdToken provided to [initializeServerApp()](./app.md#initializeserverapp_30ab697) has completed.
+
+It is recommend that your application awaits this promise before invoking getAuth() if an authIdToken was provided in the FirebaseServerAppSettings.
+
+The returned Promise is completed immediately if the optional authIdToken parameter was omitted from FirebaseServerApp initialization.
+
+<b>Signature:</b>
+
+```typescript
+authIdTokenVerified: () => Promise<void>;
+```
+
+## FirebaseServerApp.name
+
+There is no getApp operation for FirebaseServerApps, so the name is not relevant for applications. However, it may be used internally, and is declared here so that FirebaseServerApp conforms to the FirebaseApp interface declaration.
+
+<b>Signature:</b>
+
+```typescript
+name: string;
+```
+
+## FirebaseServerApp.settings
+
+The (read-only) configuration settings for this server app. These are the original parameters given in [initializeServerApp()](./app.md#initializeserverapp_30ab697)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+readonly settings: FirebaseServerAppSettings;
+```
+
+### Example
+
+
+```javascript
+const app = initializeServerApp(settings);
+console.log(app.settings.authIdToken === options.authIdToken);  // true
+
+```
+

docs-devsite/app.firebaseserverappsettings.md

@@ -0,0 +1,72 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# FirebaseServerAppSettings interface
+Configuration options given to [initializeServerApp()](./app.md#initializeserverapp_30ab697)
+
+<b>Signature:</b>
+
+```typescript
+export interface FirebaseServerAppSettings extends FirebaseAppSettings 
+```
+<b>Extends:</b> [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface)
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [authIdToken](./app.firebaseserverappsettings.md#firebaseserverappsettingsauthidtoken) | string | An optional Auth ID token used to resume a signed in user session from a client runtime environment.<!-- -->If provided, the FirebaseServerApp instance will work to validate the token even before Auth is initialized. The result of the validation can be queried via by the application by invoking . Awaiting the Promise returned by  is highly recommended if an authIdToken token is provided.<!-- -->Invoking getAuth() with a FirebaseServerApp configured with a validated authIdToken will cause an automatic attempt to sign in the user that the authIdToken represents. The token needs to have been recently minted for this operation to succeed, otherwise it will fail validation.<!-- -->If the token fails local verification, or if the Auth service has deemed it invalid when the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not sign in a user upon initalization.<!-- -->If a user is successfully signed-in, then the Auth instance's onAuthStateChanged callback will be invoked with the User as per standard Auth flows. However, users created via authIdTokens do not have a refresh token and any attempted refresh operation will fail. |
+|  [name](./app.firebaseserverappsettings.md#firebaseserverappsettingsname) | undefined | There is no get for FirebaseServerApps, so the name is not relevant. however it's always a blank string so that FirebaseServerApp conforms to the FirebaseApp interface declaration. |
+|  [releaseOnDeref](./app.firebaseserverappsettings.md#firebaseserverappsettingsreleaseonderef) | object | An optional object. If provided, the Firebase SDK will use a FinalizationRegistry object to monitor the Garbage Collection status of the provided object, and the Firebase SDK will release its refrence on the FirebaseServerApp instance when the provided object is garbage collected.<!-- -->The intent of this field is to help reduce memory overhead for long-running cloud functions. If provided, the customer's app running in a SSR pass need not worry about FirebaseServerApp cleanup, so long as the reference object is deleted (by falling out of SSR scope, for instance.)<!-- -->If an object is not provided then the application must clean up the FirebaseServerApp instance by invoking deleteApp.<!-- -->If the application provides an object in this parameter, but the application is executed in a JavaScript engine that predates the support of FinalizationRegistry (introduced in node v14.6.0, for instance), then the Firebase SDK will not be able to automatically clean up the FirebaseServerApp instance and an error will be thrown. |
+
+## FirebaseServerAppSettings.authIdToken
+
+An optional Auth ID token used to resume a signed in user session from a client runtime environment.
+
+If provided, the FirebaseServerApp instance will work to validate the token even before Auth is initialized. The result of the validation can be queried via by the application by invoking . Awaiting the Promise returned by  is highly recommended if an authIdToken token is provided.
+
+Invoking getAuth() with a FirebaseServerApp configured with a validated authIdToken will cause an automatic attempt to sign in the user that the authIdToken represents. The token needs to have been recently minted for this operation to succeed, otherwise it will fail validation.
+
+If the token fails local verification, or if the Auth service has deemed it invalid when the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not sign in a user upon initalization.
+
+If a user is successfully signed-in, then the Auth instance's onAuthStateChanged callback will be invoked with the User as per standard Auth flows. However, users created via authIdTokens do not have a refresh token and any attempted refresh operation will fail.
+
+<b>Signature:</b>
+
+```typescript
+authIdToken?: string;
+```
+
+## FirebaseServerAppSettings.name
+
+There is no get for FirebaseServerApps, so the name is not relevant. however it's always a blank string so that FirebaseServerApp conforms to the FirebaseApp interface declaration.
+
+<b>Signature:</b>
+
+```typescript
+name?: undefined;
+```
+
+## FirebaseServerAppSettings.releaseOnDeref
+
+An optional object. If provided, the Firebase SDK will use a FinalizationRegistry object to monitor the Garbage Collection status of the provided object, and the Firebase SDK will release its refrence on the FirebaseServerApp instance when the provided object is garbage collected.
+
+The intent of this field is to help reduce memory overhead for long-running cloud functions. If provided, the customer's app running in a SSR pass need not worry about FirebaseServerApp cleanup, so long as the reference object is deleted (by falling out of SSR scope, for instance.)
+
+If an object is not provided then the application must clean up the FirebaseServerApp instance by invoking deleteApp.
+
+If the application provides an object in this parameter, but the application is executed in a JavaScript engine that predates the support of FinalizationRegistry (introduced in node v14.6.0, for instance), then the Firebase SDK will not be able to automatically clean up the FirebaseServerApp instance and an error will be thrown.
+
+<b>Signature:</b>
+
+```typescript
+releaseOnDeref?: object;
+```

docs-devsite/app.md

@@ -34,6 +34,7 @@ This package coordinates the communication between the different Firebase compon
 |  <b>function(options, ...)</b> |
 |  [initializeApp(options, name)](./app.md#initializeapp_cb2f5e1) | Creates and initializes a [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) instance.<!-- -->See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. |
 |  [initializeApp(options, config)](./app.md#initializeapp_079e917) | Creates and initializes a FirebaseApp instance. |
+|  [initializeServerApp(options, config)](./app.md#initializeserverapp_30ab697) | Creates and initializes a [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface) instance.<!-- -->The FirebaseServerApp is similar to FirebaseApp, but is intended for execution in server side rendering environments only. Initialization will fail if invoked from a browser environment.<!-- -->See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation. |
 
 ## Interfaces
 
@@ -42,11 +43,14 @@ This package coordinates the communication between the different Firebase compon
 |  [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | A [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) holds the initialization information for a collection of services.<!-- -->Do not call this constructor directly. Instead, use [initializeApp()](./app.md#initializeapp_cb2f5e1) to create an app. |
 |  [FirebaseAppSettings](./app.firebaseappsettings.md#firebaseappsettings_interface) | Configuration options given to [initializeApp()](./app.md#initializeapp_cb2f5e1) |
 |  [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) | Firebase configuration object. Contains a set of parameters required by services in order to successfully communicate with Firebase server APIs and to associate client data with your Firebase project and Firebase application. Typically this object is populated by the Firebase console at project setup. See also: [Learn about the Firebase config object](https://firebase.google.com/docs/web/setup#config-object)<!-- -->. |
+|  [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface) | A [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface) holds the initialization information for a collection of services running in server enviornments.<!-- -->Do not call this constructor directly. Instead, use [initializeServerApp()](./app.md#initializeserverapp_30ab697) to create an app. |
+|  [FirebaseServerAppSettings](./app.firebaseserverappsettings.md#firebaseserverappsettings_interface) | Configuration options given to [initializeServerApp()](./app.md#initializeserverapp_30ab697) |
 
 ## Variables
 
 |  Variable | Description |
 |  --- | --- |
+|  [\_serverApps](./app.md#_serverapps) |  |
 |  [SDK\_VERSION](./app.md#sdk_version) | The current SDK version. |
 
 ## function(app, ...)
@@ -309,6 +313,62 @@ export declare function initializeApp(options: FirebaseOptions, config?: Firebas
 
 [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)
 
+### initializeServerApp(options, config) {:#initializeserverapp_30ab697}
+
+Creates and initializes a [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface) instance.
+
+The FirebaseServerApp is similar to FirebaseApp, but is intended for execution in server side rendering environments only. Initialization will fail if invoked from a browser environment.
+
+See [Add Firebase to your app](https://firebase.google.com/docs/web/setup#add_firebase_to_your_app) and [Initialize multiple projects](https://firebase.google.com/docs/web/setup#multiple-projects) for detailed documentation.
+
+<b>Signature:</b>
+
+```typescript
+export declare function initializeServerApp(options: FirebaseOptions | FirebaseApp, config: FirebaseServerAppSettings): FirebaseServerApp;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  options | [FirebaseOptions](./app.firebaseoptions.md#firebaseoptions_interface) \| [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface) | Firebase.AppOptions to configure the app's services, or a a FirebaseApp instance which contains the AppOptions within. |
+|  config | [FirebaseServerAppSettings](./app.firebaseserverappsettings.md#firebaseserverappsettings_interface) | FirebaseServerApp configuration. |
+
+<b>Returns:</b>
+
+[FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface)
+
+The initialized FirebaseServerApp.
+
+### Example
+
+
+```javascript
+
+// Initialize a FirebaseServerApp.
+// Retrieve your own options values by adding a web app on
+// https://console.firebase.google.com
+initializeServerApp({
+    apiKey: "AIza....",                             // Auth / General Use
+    authDomain: "YOUR_APP.firebaseapp.com",         // Auth with popup/redirect
+    databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database
+    storageBucket: "YOUR_APP.appspot.com",          // Storage
+    messagingSenderId: "123456789"                  // Cloud Messaging
+  },
+  {
+   authIdToken: "Your Auth ID Token"
+  });
+
+```
+
+## \_serverApps
+
+<b>Signature:</b>
+
+```typescript
+_serverApps: Map<string, FirebaseServerApp>
+```
+
 ## SDK\_VERSION
 
 The current SDK version.