API for managing RTDB Security Rules (#595)

* Adding RTDB rules management APIs

* Added more test cases

* Getting to 100% unit test coverage

* Added more input validation; tests

* Handling URLs with query params

* Rejecting on invalid arguments

* Removing unused attribute

* Removing unused imports

* Cleaned up the tests

* Updated changelog

* Updated documentation text

Author: hiranya911

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Unreleased
 
--
+- [added] `admin.database().getRules()` method to retrieve the currently
+  applied RTDB rules text.
+- [added] `admin.database().getRulesJSON()` method to retrieve the currently
+  applied RTDB rules as a parsed JSON object.
+- [added] `admin.database().setRules()` method to update the RTDB rules.
 
 # v8.2.0
 

src/database/database.ts

@@ -1,9 +1,13 @@
+import {URL} from 'url';
+import * as path from 'path';
+
 import {FirebaseApp} from '../firebase-app';
-import {FirebaseDatabaseError} from '../utils/error';
+import {FirebaseDatabaseError, AppErrorCodes} from '../utils/error';
 import {FirebaseServiceInterface, FirebaseServiceInternalsInterface} from '../firebase-service';
 import {Database} from '@firebase/database';
 
 import * as validator from '../utils/validator';
+import { AuthorizedHttpClient, HttpRequestConfig, HttpError } from '../utils/api-request';
 
 /**
  * This variable is redefined in the firebase-js-sdk. Before modifying this
@@ -37,11 +41,19 @@ class DatabaseInternals implements FirebaseServiceInternalsInterface {
   }
 }
 
+declare module '@firebase/database' {
+  interface Database {
+    getRules(): Promise<string>;
+    getRulesJSON(): Promise<object>;
+    setRules(source: string | Buffer | object): Promise<void>;
+  }
+}
+
 export class DatabaseService implements FirebaseServiceInterface {
 
-  public INTERNAL: DatabaseInternals = new DatabaseInternals();
+  public readonly INTERNAL: DatabaseInternals = new DatabaseInternals();
 
-  private appInternal: FirebaseApp;
+  private readonly appInternal: FirebaseApp;
 
   constructor(app: FirebaseApp) {
     if (!validator.isNonNullObject(app) || !('options' in app)) {
@@ -76,6 +88,18 @@ export class DatabaseService implements FirebaseServiceInterface {
       const rtdb = require('@firebase/database');
       const { version } = require('../../package.json');
       db = rtdb.initStandalone(this.appInternal, dbUrl, version).instance;
+
+      const rulesClient = new DatabaseRulesClient(this.app, dbUrl);
+      db.getRules = () => {
+        return rulesClient.getRules();
+      };
+      db.getRulesJSON = () => {
+        return rulesClient.getRulesJSON();
+      };
+      db.setRules = (source) => {
+        return rulesClient.setRules(source);
+      };
+
       this.INTERNAL.databases[dbUrl] = db;
     }
     return db;
@@ -97,3 +121,122 @@ export class DatabaseService implements FirebaseServiceInterface {
     });
   }
 }
+
+const RULES_URL_PATH = '.settings/rules.json';
+
+/**
+ * A helper client for managing RTDB security rules.
+ */
+class DatabaseRulesClient {
+
+  private readonly dbUrl: string;
+  private readonly httpClient: AuthorizedHttpClient;
+
+  constructor(app: FirebaseApp, dbUrl: string) {
+    const parsedUrl = new URL(dbUrl);
+    parsedUrl.pathname = path.join(parsedUrl.pathname, RULES_URL_PATH);
+    this.dbUrl = parsedUrl.toString();
+    this.httpClient = new AuthorizedHttpClient(app);
+  }
+
+  /**
+   * Gets the currently applied security rules as a string. The return value consists of
+   * the rules source including comments.
+   *
+   * @return {Promise<string>} A promise fulfilled with the rules as a raw string.
+   */
+  public getRules(): Promise<string> {
+    const req: HttpRequestConfig = {
+      method: 'GET',
+      url: this.dbUrl,
+    };
+    return this.httpClient.send(req)
+      .then((resp) => {
+        return resp.text;
+      })
+      .catch((err) => {
+        throw this.handleError(err);
+      });
+  }
+
+  /**
+   * Gets the currently applied security rules as a parsed JSON object. Any comments in
+   * the original source are stripped away.
+   *
+   * @return {Promise<object>} A promise fulfilled with the parsed rules source.
+   */
+  public getRulesJSON(): Promise<object> {
+    const req: HttpRequestConfig = {
+      method: 'GET',
+      url: this.dbUrl,
+      data: {format: 'strict'},
+    };
+    return this.httpClient.send(req)
+      .then((resp) => {
+        return resp.data;
+      })
+      .catch((err) => {
+        throw this.handleError(err);
+      });
+  }
+
+  /**
+   * Sets the specified rules on the Firebase Database instance. If the rules source is
+   * specified as a string or a Buffer, it may include comments.
+   *
+   * @param {string|Buffer|object} source Source of the rules to apply. Must not be `null`
+   *  or empty.
+   * @return {Promise<void>} Resolves when the rules are set on the Database.
+   */
+  public setRules(source: string | Buffer | object): Promise<void> {
+    if (!validator.isNonEmptyString(source) &&
+      !validator.isBuffer(source)  &&
+      !validator.isNonNullObject(source)) {
+        const error = new FirebaseDatabaseError({
+          code: 'invalid-argument',
+          message: 'Source must be a non-empty string, Buffer or an object.',
+        });
+        return Promise.reject(error);
+    }
+
+    const req: HttpRequestConfig = {
+      method: 'PUT',
+      url: this.dbUrl,
+      data: source,
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+      },
+    };
+    return this.httpClient.send(req)
+      .then(() => {
+        return;
+      })
+      .catch((err) => {
+        throw this.handleError(err);
+      });
+  }
+
+  private handleError(err: Error): Error {
+    if (err instanceof HttpError) {
+      return new FirebaseDatabaseError({
+        code: AppErrorCodes.INTERNAL_ERROR,
+        message: this.getErrorMessage(err),
+      });
+    }
+    return err;
+  }
+
+  private getErrorMessage(err: HttpError): string {
+    const intro = 'Error while accessing security rules';
+    try {
+      const body: {error?: string} = err.response.data;
+      if (body && body.error) {
+        return `${intro}: ${body.error.trim()}`;
+      }
+    } catch {
+      // Ignore parsing errors
+    }
+
+    return `${intro}: ${err.response.text}`;
+  }
+}

src/index.d.ts

@@ -2064,6 +2064,31 @@ declare namespace admin.database {
      * @return  A `Reference` pointing to the provided Firebase URL.
      */
     refFromURL(url: string): admin.database.Reference;
+
+    /**
+     * Gets the currently applied security rules as a string. The return value consists of
+     * the rules source including comments.
+     *
+     * @return A promise fulfilled with the rules as a raw string.
+     */
+    getRules(): Promise<string>;
+
+    /**
+     * Gets the currently applied security rules as a parsed JSON object. Any comments in
+     * the original source are stripped away.
+     *
+     * @return A promise fulfilled with the parsed rules object.
+     */
+    getRulesJSON(): Promise<object>;
+
+    /**
+     * Sets the specified rules on the Firebase Realtime Database instance. If the rules source is
+     * specified as a string or a Buffer, it may include comments.
+     *
+     * @param source Source of the rules to apply. Must not be `null` or empty.
+     * @return Resolves when the rules are set on the Realtime Database.
+     */
+    setRules(source: string | Buffer | object): Promise<void>;
   }
 
   /**

test/integration/database.spec.ts

@@ -21,7 +21,6 @@ import url = require('url');
 import {defaultApp, nullApp, nonNullApp, cmdArgs, databaseUrl} from './setup';
 
 /* tslint:disable:no-var-requires */
-const apiRequest = require('../../lib/utils/api-request');
 const chalk = require('chalk');
 /* tslint:enable:no-var-requires */
 
@@ -43,20 +42,13 @@ describe('admin.database', () => {
     }
     console.log(chalk.yellow('    Updating security rules to defaults.'));
     /* tslint:enable:no-console */
-    const client = new apiRequest.AuthorizedHttpClient(defaultApp);
-    const dbUrl =  url.parse(databaseUrl);
     const defaultRules = {
       rules : {
         '.read': 'auth != null',
         '.write': 'auth != null',
       },
     };
-    return client.send({
-      url: `https://${dbUrl.host}/.settings/rules.json`,
-      method: 'PUT',
-      data: defaultRules,
-      timeout: 10000,
-    });
+    return admin.database().setRules(defaultRules);
   });
 
   it('admin.database() returns a database client', () => {
@@ -166,6 +158,18 @@ describe('admin.database', () => {
       return refWithUrl.remove().should.eventually.be.fulfilled;
     });
   });
+
+  it('admin.database().getRules() returns currently defined rules as a string', () => {
+    return admin.database().getRules().then((result) => {
+      return expect(result).to.be.not.empty;
+    });
+  });
+
+  it('admin.database().getRulesJSON() returns currently defined rules as an object', () => {
+    return admin.database().getRulesJSON().then((result) => {
+      return expect(result).to.be.not.undefined;
+    });
+  });
 });
 
 function addValueEventListener(