chore(rules): Exposed admin.securiryRules namespace (#1050)

hiranya911 · web-flow · commit 77d8c0cc264d · 2020-10-01T12:10:43.000-07:00
diff --git a/gulpfile.js b/gulpfile.js
@@ -89,6 +89,7 @@ gulp.task('compile', function() {
     'lib/instance-id/index.d.ts',
     'lib/messaging/index.d.ts',
     'lib/remote-config/index.d.ts',
+    'lib/security-rules/index.d.ts',
   ];
 
   workflow = workflow.pipe(filter(configuration));
diff --git a/src/firebase-namespace-api.ts b/src/firebase-namespace-api.ts
@@ -20,6 +20,7 @@ import { database } from './database/index';
 import { instanceId } from './instance-id/index';
 import { messaging } from './messaging/index';
 import { remoteConfig } from './remote-config/index';
+import { securityRules } from './security-rules/index';
 
 /**
  * `FirebaseError` is a subclass of the standard JavaScript `Error` object. In
@@ -220,6 +221,7 @@ export namespace app {
     instanceId(): instanceId.InstanceId;
     messaging(): messaging.Messaging;
     remoteConfig(): remoteConfig.RemoteConfig;
+    securityRules(): securityRules.SecurityRules;
 
     /**
      * Renders this local `FirebaseApp` unusable and frees the resources of
diff --git a/src/firebase-namespace.d.ts b/src/firebase-namespace.d.ts
@@ -20,3 +20,4 @@ export * from './database/index';
 export * from './instance-id/index';
 export * from './messaging/index';
 export * from './remote-config/index';
+export * from './security-rules/index';
diff --git a/src/security-rules/index.ts b/src/security-rules/index.ts
@@ -14,28 +14,226 @@
  * limitations under the License.
  */
 
-import { FirebaseApp } from '../firebase-app';
-import * as securityRulesApi from './security-rules';
-
-export declare function securityRules(app?: FirebaseApp): securityRulesApi.SecurityRules;
+import { app } from '../firebase-namespace-api';
 
 /**
- * We must define a namespace to make the typings work correctly. Otherwise
- * `admin.securityRules()` cannot be called like a function. Temporarily,
- * admin.securityRules is used as the namespace name because we cannot barrel
- * re-export the contents from security-rules, and we want it to
- * match the namespacing in the re-export inside src/index.d.ts
+ * Gets the {@link admin.securityRules.SecurityRules
+ * `SecurityRules`} service for the default app or a given app.
+ *
+ * `admin.securityRules()` can be called with no arguments to access the
+ * default app's {@link admin.securityRules.SecurityRules
+ * `SecurityRules`} service, or as `admin.securityRules(app)` to access
+ * the {@link admin.securityRules.SecurityRules `SecurityRules`}
+ * service associated with a specific app.
+ *
+ * @example
+ * ```javascript
+ * // Get the SecurityRules service for the default app
+ * var defaultSecurityRules = admin.securityRules();
+ * ```
+ *
+ * @example
+ *  ```javascript
+ * // Get the SecurityRules service for a given app
+ * var otherSecurityRules = admin.securityRules(otherApp);
+ * ```
+ *
+ * @param app Optional app to return the `SecurityRules` service
+ *     for. If not provided, the default `SecurityRules` service
+ *     is returned.
+ * @return The default `SecurityRules` service if no app is provided, or the
+ *   `SecurityRules` service associated with the provided app.
  */
+export declare function securityRules(app?: app.App): securityRules.SecurityRules;
+
 /* eslint-disable @typescript-eslint/no-namespace */
-export namespace admin.securityRules {
-  // See https://github.com/microsoft/TypeScript/issues/4336
-  /* eslint-disable @typescript-eslint/no-unused-vars */
-  // See https://github.com/typescript-eslint/typescript-eslint/issues/363
-  export import RulesFile = securityRulesApi.RulesFile;
-  export import RulesetMetadata = securityRulesApi.RulesetMetadata;
-  export import RulesetMetadataList = securityRulesApi.RulesetMetadataList;
-
-  /* eslint-disable @typescript-eslint/no-empty-interface */
-  export interface Ruleset extends securityRulesApi.Ruleset {}
-  export interface SecurityRules extends securityRulesApi.SecurityRules {}
+export namespace securityRules {
+  /**
+   * A source file containing some Firebase security rules. The content includes raw
+   * source code including text formatting, indentation and comments. Use the
+   * [`securityRules.createRulesFileFromSource()`](admin.securityRules.SecurityRules#createRulesFileFromSource)
+   * method to create new instances of this type.
+   */
+  export interface RulesFile {
+    readonly name: string;
+    readonly content: string;
+  }
+
+  /**
+   * Required metadata associated with a ruleset.
+   */
+  export interface RulesetMetadata {
+    /**
+     * Name of the `Ruleset` as a short string. This can be directly passed into APIs
+     * like [`securityRules.getRuleset()`](admin.securityRules.SecurityRules#getRuleset)
+     * and [`securityRules.deleteRuleset()`](admin.securityRules.SecurityRules#deleteRuleset).
+     */
+    readonly name: string;
+    /**
+     * Creation time of the `Ruleset` as a UTC timestamp string.
+     */
+    readonly createTime: string;
+  }
+
+  /**
+   * A page of ruleset metadata.
+   */
+  export interface RulesetMetadataList {
+    /**
+     * A batch of ruleset metadata.
+     */
+    readonly rulesets: RulesetMetadata[];
+    /**
+     * The next page token if available. This is needed to retrieve the next batch.
+     */
+    readonly nextPageToken?: string;
+  }
+
+  /**
+   * A set of Firebase security rules.
+   */
+  export interface Ruleset extends RulesetMetadata {
+    readonly source: RulesFile[];
+  }
+
+  /**
+   * The Firebase `SecurityRules` service interface.
+   *
+   * Do not call this constructor directly. Instead, use
+   * [`admin.securityRules()`](admin.securityRules#securityRules).
+   */
+  export interface SecurityRules {
+    app: app.App;
+
+    /**
+     * Creates a {@link admin.securityRules.RulesFile `RuleFile`} with the given name
+     * and source. Throws an error if any of the arguments are invalid. This is a local
+     * operation, and does not involve any network API calls.
+     *
+     * @example
+     * ```javascript
+     * const source = '// Some rules source';
+     * const rulesFile = admin.securityRules().createRulesFileFromSource(
+     *   'firestore.rules', source);
+     * ```
+     *
+     * @param name Name to assign to the rules file. This is usually a short file name that
+     *   helps identify the file in a ruleset.
+     * @param source Contents of the rules file.
+     * @return A new rules file instance.
+     */
+    createRulesFileFromSource(name: string, source: string | Buffer): RulesFile;
+
+    /**
+     * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given
+     * {@link admin.securityRules.RulesFile `RuleFile`}.
+     *
+     * @param file Rules file to include in the new `Ruleset`.
+     * @returns A promise that fulfills with the newly created `Ruleset`.
+     */
+    createRuleset(file: RulesFile): Promise<Ruleset>;
+
+    /**
+     * Gets the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given
+     * name. The input name should be the short name string without the project ID
+     * prefix. For example, to retrieve the `projects/project-id/rulesets/my-ruleset`,
+     * pass the short name "my-ruleset". Rejects with a `not-found` error if the
+     * specified `Ruleset` cannot be found.
+     *
+     * @param name Name of the `Ruleset` to retrieve.
+     * @return A promise that fulfills with the specified `Ruleset`.
+     */
+    getRuleset(name: string): Promise<Ruleset>;
+
+    /**
+     * Deletes the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given
+     * name. The input name should be the short name string without the project ID
+     * prefix. For example, to delete the `projects/project-id/rulesets/my-ruleset`,
+     * pass the  short name "my-ruleset". Rejects with a `not-found` error if the
+     * specified `Ruleset` cannot be found.
+     *
+     * @param name Name of the `Ruleset` to delete.
+     * @return A promise that fulfills when the `Ruleset` is deleted.
+     */
+    deleteRuleset(name: string): Promise<void>;
+
+    /**
+     * Retrieves a page of ruleset metadata.
+     *
+     * @param pageSize The page size, 100 if undefined. This is also the maximum allowed
+     *   limit.
+     * @param nextPageToken The next page token. If not specified, returns rulesets
+     *   starting without any offset.
+     * @return A promise that fulfills with a page of rulesets.
+     */
+    listRulesetMetadata(
+      pageSize?: number, nextPageToken?: string): Promise<RulesetMetadataList>;
+
+    /**
+     * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to
+     * Cloud Firestore. Rejects with a `not-found` error if no ruleset is applied
+     * on Firestore.
+     *
+     * @return A promise that fulfills with the Firestore ruleset.
+     */
+    getFirestoreRuleset(): Promise<Ruleset>;
+
+    /**
+     * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given
+     * source, and applies it to Cloud Firestore.
+     *
+     * @param source Rules source to apply.
+     * @return A promise that fulfills when the ruleset is created and released.
+     */
+    releaseFirestoreRulesetFromSource(source: string | Buffer): Promise<Ruleset>;
+
+    /**
+     * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset
+     * to Cloud Firestore.
+     *
+     * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object
+     *   containing the name.
+     * @return A promise that fulfills when the ruleset is released.
+     */
+    releaseFirestoreRuleset(ruleset: string | RulesetMetadata): Promise<void>;
+
+    /**
+     * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to a
+     * Cloud Storage bucket. Rejects with a `not-found` error if no ruleset is applied
+     * on the bucket.
+     *
+     * @param bucket Optional name of the Cloud Storage bucket to be retrieved. If not
+     *   specified, retrieves the ruleset applied on the default bucket configured via
+     *   `AppOptions`.
+     * @return A promise that fulfills with the Cloud Storage ruleset.
+     */
+    getStorageRuleset(bucket?: string): Promise<Ruleset>;
+
+    /**
+     * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given
+     * source, and applies it to a Cloud Storage bucket.
+     *
+     * @param source Rules source to apply.
+     * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If
+     *   not specified, applies the ruleset on the default bucket configured via
+     *   {@link admin.AppOptions `AppOptions`}.
+     * @return A promise that fulfills when the ruleset is created and released.
+     */
+    releaseStorageRulesetFromSource(
+      source: string | Buffer, bucket?: string): Promise<Ruleset>;
+
+    /**
+     * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset
+     * to a Cloud Storage bucket.
+     *
+     * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object
+     *   containing the name.
+     * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If
+     *   not specified, applies the ruleset on the default bucket configured via
+     *   {@link admin.AppOptions `AppOptions`}.
+     * @return A promise that fulfills when the ruleset is released.
+     */
+    releaseStorageRuleset(
+      ruleset: string | RulesetMetadata, bucket?: string): Promise<void>;
+  }
 }
diff --git a/src/security-rules/security-rules.ts b/src/security-rules/security-rules.ts
@@ -21,47 +21,13 @@ import {
   SecurityRulesApiClient, RulesetResponse, RulesetContent, ListRulesetsResponse,
 } from './security-rules-api-client-internal';
 import { FirebaseSecurityRulesError } from './security-rules-internal';
+import { securityRules } from './index';
 
-/**
- * A source file containing some Firebase security rules. The content includes raw
- * source code including text formatting, indentation and comments. Use the
- * [`securityRules.createRulesFileFromSource()`](admin.securityRules.SecurityRules#createRulesFileFromSource)
- * method to create new instances of this type.
- */
-export interface RulesFile {
-  readonly name: string;
-  readonly content: string;
-}
-
-/**
- * Required metadata associated with a ruleset.
- */
-export interface RulesetMetadata {
-  /**
-   * Name of the `Ruleset` as a short string. This can be directly passed into APIs
-   * like [`securityRules.getRuleset()`](admin.securityRules.SecurityRules#getRuleset)
-   * and [`securityRules.deleteRuleset()`](admin.securityRules.SecurityRules#deleteRuleset).
-   */
-  readonly name: string;
-  /**
-   * Creation time of the `Ruleset` as a UTC timestamp string.
-   */
-  readonly createTime: string;
-}
-
-/**
- * A page of ruleset metadata.
- */
-export interface RulesetMetadataList {
-  /**
-   * A batch of ruleset metadata.
-   */
-  readonly rulesets: RulesetMetadata[];
-  /**
-   * The next page token if available. This is needed to retrieve the next batch.
-   */
-  readonly nextPageToken?: string;
-}
+import RulesFile = securityRules.RulesFile;
+import RulesetMetadata = securityRules.RulesetMetadata;
+import RulesetMetadataList = securityRules.RulesetMetadataList;
+import RulesetInterface = securityRules.Ruleset;
+import SecurityRulesInterface = securityRules.SecurityRules;
 
 class RulesetMetadataListImpl implements RulesetMetadataList {
 
@@ -91,7 +57,7 @@ class RulesetMetadataListImpl implements RulesetMetadataList {
 /**
  * Represents a set of Firebase security rules.
  */
-export class Ruleset implements RulesetMetadata {
+export class Ruleset implements RulesetInterface {
 
   public readonly name: string;
   public readonly createTime: string;
@@ -119,7 +85,7 @@ export class Ruleset implements RulesetMetadata {
  * Do not call this constructor directly. Instead, use
  * [`admin.securityRules()`](admin.securityRules#securityRules).
  */
-export class SecurityRules implements FirebaseServiceInterface {
+export class SecurityRules implements FirebaseServiceInterface, SecurityRulesInterface {
 
   private static readonly CLOUD_FIRESTORE = 'cloud.firestore';
   private static readonly FIREBASE_STORAGE = 'firebase.storage';
