[ServerApp] Firebase Server App feature branch (#8005)

Feature branch merge for the addition of FirebaseServerApp - a tool to ease the use of working with Firebase in SSR frameworks.

.changeset/afraid-fishes-repair.md

@@ -0,0 +1,8 @@
+---
+'@firebase/auth': minor
+'@firebase/app': minor
+'firebase': minor
+---
+
+Added the new `FirebaseServerApp` interface to bridge state
+data between client and server runtime environments. This interface extends `FirebaseApp`.

common/api-review/app.api.md

@@ -71,6 +71,19 @@ export interface FirebaseOptions {
     storageBucket?: string;
 }
 
+// @public
+export interface FirebaseServerApp extends FirebaseApp {
+    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 +109,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 +133,9 @@ export function _removeServiceInstance<T extends Name>(app: FirebaseApp, name: T
 // @public
 export const SDK_VERSION: string;
 
+// @internal (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,59 @@
+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 environments.
+
+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 |
+|  --- | --- | --- |
+|  [name](./app.firebaseserverapp.md#firebaseserverappname) | string | There is no <code>getApp()</code> operation for <code>FirebaseServerApp</code>, so the name is not relevant for applications. However, it may be used internally, and is declared here so that <code>FirebaseServerApp</code> conforms to the <code>FirebaseApp</code> interface. |
+|  [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.name
+
+There is no `getApp()` operation for `FirebaseServerApp`<!-- -->, 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.
+
+<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,70 @@
+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.<!-- -->Invoking <code>getAuth</code> with a <code>FirebaseServerApp</code> configured with a validated <code>authIdToken</code> causes an automatic attempt to sign in the user that the <code>authIdToken</code> represents. The token needs to have been recently minted for this operation to succeed.<!-- -->If the token fails local verification, or if the Auth service has failed to validate it when the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not sign in a user on initalization.<!-- -->If a user is successfully signed in, then the Auth instance's <code>onAuthStateChanged</code> callback is invoked with the <code>User</code> object as per standard Auth flows. However, <code>User</code> objects created via an <code>authIdToken</code> do not have a refresh token. Attempted <code>refreshToken</code> operations fail. |
+|  [name](./app.firebaseserverappsettings.md#firebaseserverappsettingsname) | undefined | There is no <code>getApp()</code> operation for <code>FirebaseServerApp</code>, so the name is not relevant for applications. However, it may be used internally, and is declared here so that <code>FirebaseServerApp</code> conforms to the <code>FirebaseApp</code> interface. |
+|  [releaseOnDeref](./app.firebaseserverappsettings.md#firebaseserverappsettingsreleaseonderef) | object | An optional object. If provided, the Firebase SDK uses a <code>FinalizationRegistry</code> object to monitor the garbage collection status of the provided object. The Firebase SDK releases its reference on the <code>FirebaseServerApp</code> instance when the provided <code>releaseOnDeref</code> object is garbage collected.<!-- -->You can use this field to reduce memory management overhead for your application. If provided, an app running in a SSR pass does not need to perform <code>FirebaseServerApp</code> 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 <code>FirebaseServerApp</code> instance by invoking <code>deleteApp</code>.<!-- -->If the application provides an object in this parameter, but the application is executed in a JavaScript engine that predates the support of <code>FinalizationRegistry</code> (introduced in node v14.6.0, for instance), then an error is thrown at <code>FirebaseServerApp</code> initialization. |
+
+## FirebaseServerAppSettings.authIdToken
+
+An optional Auth ID token used to resume a signed in user session from a client runtime environment.
+
+Invoking `getAuth` with a `FirebaseServerApp` configured with a validated `authIdToken` causes 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.
+
+If the token fails local verification, or if the Auth service has failed to validate it when the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not sign in a user on initalization.
+
+If a user is successfully signed in, then the Auth instance's `onAuthStateChanged` callback is invoked with the `User` object as per standard Auth flows. However, `User` objects created via an `authIdToken` do not have a refresh token. Attempted `refreshToken` operations fail.
+
+<b>Signature:</b>
+
+```typescript
+authIdToken?: string;
+```
+
+## FirebaseServerAppSettings.name
+
+There is no `getApp()` operation for `FirebaseServerApp`<!-- -->, 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.
+
+<b>Signature:</b>
+
+```typescript
+name?: undefined;
+```
+
+## FirebaseServerAppSettings.releaseOnDeref
+
+An optional object. If provided, the Firebase SDK uses a `FinalizationRegistry` object to monitor the garbage collection status of the provided object. The Firebase SDK releases its reference on the `FirebaseServerApp` instance when the provided `releaseOnDeref` object is garbage collected.
+
+You can use this field to reduce memory management overhead for your application. If provided, an app running in a SSR pass does not need to perform `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 an error is thrown at `FirebaseServerApp` initialization.
+
+<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 <code>FirebaseServerApp</code> is similar to <code>FirebaseApp</code>, 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,6 +43,8 @@ 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 environments.<!-- -->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
 
@@ -309,6 +312,54 @@ 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) | <code>Firebase.AppOptions</code> to configure the app's services, or a a <code>FirebaseApp</code> instance which contains the <code>AppOptions</code> within. |
+|  config | [FirebaseServerAppSettings](./app.firebaseserverappsettings.md#firebaseserverappsettings_interface) | <code>FirebaseServerApp</code> configuration. |
+
+<b>Returns:</b>
+
+[FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface)
+
+The initialized `FirebaseServerApp`<!-- -->.
+
+### Example
+
+
+```javascript
+
+// Initialize an instance of `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"
+  });
+
+```
+
 ## SDK\_VERSION
 
 The current SDK version.

docs-devsite/auth.auth.md

@@ -265,6 +265,8 @@ auth.setPersistence(browserSessionPersistence);
 
 Signs out the current user. This does not automatically revoke the user's ID token.
 
+This method is not supported by [Auth](./auth.auth.md#auth_interface) instances created with a [FirebaseServerApp](./app.firebaseserverapp.md#firebaseserverapp_interface)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript