Container contract support for Firebase Functions SDK (#1014)

* Annotate function triggers with __endpoint property (#999)

In addition to annotating function triggers with `__trigger` property, we add `__endpoint` annotation. This property will be used by the to-be-developed functions runtime to generate/declare deployment manifest that the CLI will use to deploy the function.

There are lots of code duplication between the utility functions for annotating the `__trigger` and `__endpoint` properties. I didn't try to refactor the common code since I expect that we will favor `__endpoint` property in the future.

* Add missing import.

* More of annotate endpoint property for functions (#1009)

Follows up #999 to annotate each funuctions with `__endpoint` property.

Highlight of changes:

* Extend unit test coverage for all v1 providers
* Add `__endpoint` annotation to v1 task queue functions
* Add `__requiredAPIs` annotation to task queue and scheduler functions
* Explicitly set `__endpoint` to undefined in the handler namespace
* No SDK-level label setting in the __endpoint annotation.

Author: taeold

spec/v1/cloud-functions.spec.ts

@@ -41,32 +41,136 @@ describe('makeCloudFunction', () => {
     legacyEventType: 'providers/provider/eventTypes/event',
   };
 
-  it('should put a __trigger on the returned CloudFunction', () => {
+  it('should put a __trigger/__endpoint on the returned CloudFunction', () => {
     const cf = makeCloudFunction({
       provider: 'mock.provider',
       eventType: 'mock.event',
       service: 'service',
       triggerResource: () => 'resource',
       handler: () => null,
     });
+
     expect(cf.__trigger).to.deep.equal({
       eventTrigger: {
         eventType: 'mock.provider.mock.event',
         resource: 'resource',
         service: 'service',
       },
     });
+
+    expect(cf.__endpoint).to.deep.equal({
+      platform: 'gcfv1',
+      eventTrigger: {
+        eventType: 'mock.provider.mock.event',
+        eventFilters: {
+          resource: 'resource',
+        },
+        retry: false,
+      },
+      labels: {},
+    });
   });
 
-  it('should have legacy event type in __trigger if provided', () => {
+  it('should have legacy event type in __trigger/__endpoint if provided', () => {
     const cf = makeCloudFunction(cloudFunctionArgs);
+
     expect(cf.__trigger).to.deep.equal({
       eventTrigger: {
         eventType: 'providers/provider/eventTypes/event',
         resource: 'resource',
         service: 'service',
       },
     });
+
+    expect(cf.__endpoint).to.deep.equal({
+      platform: 'gcfv1',
+      eventTrigger: {
+        eventType: 'providers/provider/eventTypes/event',
+        eventFilters: {
+          resource: 'resource',
+        },
+        retry: false,
+      },
+      labels: {},
+    });
+  });
+
+  it('should include converted options in __endpoint', () => {
+    const cf = makeCloudFunction({
+      provider: 'mock.provider',
+      eventType: 'mock.event',
+      service: 'service',
+      triggerResource: () => 'resource',
+      handler: () => null,
+      options: {
+        timeoutSeconds: 10,
+        regions: ['us-central1'],
+        memory: '128MB',
+        serviceAccount: '[email protected]',
+      },
+    });
+
+    expect(cf.__endpoint).to.deep.equal({
+      platform: 'gcfv1',
+      timeoutSeconds: 10,
+      region: ['us-central1'],
+      availableMemoryMb: 128,
+      serviceAccountEmail: '[email protected]',
+      eventTrigger: {
+        eventType: 'mock.provider.mock.event',
+        eventFilters: {
+          resource: 'resource',
+        },
+        retry: false,
+      },
+      labels: {},
+    });
+  });
+
+  it('should set retry given failure policy in __endpoint', () => {
+    const cf = makeCloudFunction({
+      provider: 'mock.provider',
+      eventType: 'mock.event',
+      service: 'service',
+      triggerResource: () => 'resource',
+      handler: () => null,
+      options: { failurePolicy: { retry: {} } },
+    });
+
+    expect(cf.__endpoint).to.deep.equal({
+      platform: 'gcfv1',
+      eventTrigger: {
+        eventType: 'mock.provider.mock.event',
+        eventFilters: {
+          resource: 'resource',
+        },
+        retry: true,
+      },
+      labels: {},
+    });
+  });
+
+  it('should setup a scheduleTrigger in __endpoint given a schedule', () => {
+    const schedule = {
+      schedule: 'every 5 minutes',
+      retryConfig: { retryCount: 3 },
+      timeZone: 'America/New_York',
+    };
+    const cf = makeCloudFunction({
+      provider: 'mock.provider',
+      eventType: 'mock.event',
+      service: 'service',
+      triggerResource: () => 'resource',
+      handler: () => null,
+      options: {
+        schedule,
+      },
+    });
+    expect(cf.__endpoint).to.deep.equal({
+      platform: 'gcfv1',
+      scheduleTrigger: schedule,
+      labels: {},
+    });
   });
 
   it('should construct the right context for event', () => {

spec/v1/providers/analytics.spec.ts

@@ -50,10 +50,14 @@ describe('Analytics Functions', () => {
       expect(fn.__trigger.regions).to.deep.equal(['us-east1']);
       expect(fn.__trigger.availableMemoryMb).to.deep.equal(256);
       expect(fn.__trigger.timeout).to.deep.equal('90s');
+
+      expect(fn.__endpoint.region).to.deep.equal(['us-east1']);
+      expect(fn.__endpoint.availableMemoryMb).to.deep.equal(256);
+      expect(fn.__endpoint.timeoutSeconds).to.deep.equal(90);
     });
 
     describe('#onLog', () => {
-      it('should return a TriggerDefinition with appropriate values', () => {
+      it('should return a trigger/endpoint with appropriate values', () => {
         const cloudFunction = analytics.event('first_open').onLog(() => null);
 
         expect(cloudFunction.__trigger).to.deep.equal({
@@ -64,6 +68,19 @@ describe('Analytics Functions', () => {
             service: 'app-measurement.com',
           },
         });
+
+        expect(cloudFunction.__endpoint).to.deep.equal({
+          platform: 'gcfv1',
+          eventTrigger: {
+            eventFilters: {
+              resource: 'projects/project1/events/first_open',
+            },
+            eventType:
+              'providers/google.firebase.analytics/eventTypes/event.log',
+            retry: false,
+          },
+          labels: {},
+        });
       });
     });
 
@@ -305,11 +322,12 @@ describe('Analytics Functions', () => {
 
   describe('handler namespace', () => {
     describe('#onLog', () => {
-      it('should return an empty trigger', () => {
+      it('should return an empty trigger/endpoint', () => {
         const cloudFunction = functions.handler.analytics.event.onLog(
           () => null
         );
         expect(cloudFunction.__trigger).to.deep.equal({});
+        expect(cloudFunction.__endpoint).to.undefined;
       });
 
       it('should handle an event with the appropriate fields', () => {

spec/v1/providers/auth.spec.ts

@@ -51,12 +51,38 @@ describe('Auth Functions', () => {
   };
 
   describe('AuthBuilder', () => {
+    function expectedTrigger(project: string, eventType: string) {
+      return {
+        eventTrigger: {
+          resource: `projects/${project}`,
+          eventType: `providers/firebase.auth/eventTypes/${eventType}`,
+          service: 'firebaseauth.googleapis.com',
+        },
+      };
+    }
+
+    function expectedEndpoint(project: string, eventType: string) {
+      return {
+        platform: 'gcfv1',
+        eventTrigger: {
+          eventFilters: {
+            resource: `projects/${project}`,
+          },
+          eventType: `providers/firebase.auth/eventTypes/${eventType}`,
+          retry: false,
+        },
+        labels: {},
+      };
+    }
+
     const handler = (user: firebase.auth.UserRecord) => {
       return Promise.resolve();
     };
 
+    const project = 'project1';
+
     before(() => {
-      process.env.GCLOUD_PROJECT = 'project1';
+      process.env.GCLOUD_PROJECT = project;
     });
 
     after(() => {
@@ -76,31 +102,37 @@ describe('Auth Functions', () => {
       expect(fn.__trigger.regions).to.deep.equal(['us-east1']);
       expect(fn.__trigger.availableMemoryMb).to.deep.equal(256);
       expect(fn.__trigger.timeout).to.deep.equal('90s');
+
+      expect(fn.__endpoint.region).to.deep.equal(['us-east1']);
+      expect(fn.__endpoint.availableMemoryMb).to.deep.equal(256);
+      expect(fn.__endpoint.timeoutSeconds).to.deep.equal(90);
     });
 
     describe('#onCreate', () => {
-      it('should return a TriggerDefinition with appropriate values', () => {
+      it('should return a trigger/endpoint with appropriate values', () => {
         const cloudFunction = auth.user().onCreate(() => null);
-        expect(cloudFunction.__trigger).to.deep.equal({
-          eventTrigger: {
-            eventType: 'providers/firebase.auth/eventTypes/user.create',
-            resource: 'projects/project1',
-            service: 'firebaseauth.googleapis.com',
-          },
-        });
+
+        expect(cloudFunction.__trigger).to.deep.equal(
+          expectedTrigger(project, 'user.create')
+        );
+
+        expect(cloudFunction.__endpoint).to.deep.equal(
+          expectedEndpoint(project, 'user.create')
+        );
       });
     });
 
     describe('#onDelete', () => {
-      it('should return a TriggerDefinition with appropriate values', () => {
+      it('should return a trigger/endpoint with appropriate values', () => {
         const cloudFunction = auth.user().onDelete(handler);
-        expect(cloudFunction.__trigger).to.deep.equal({
-          eventTrigger: {
-            eventType: 'providers/firebase.auth/eventTypes/user.delete',
-            resource: 'projects/project1',
-            service: 'firebaseauth.googleapis.com',
-          },
-        });
+
+        expect(cloudFunction.__trigger).to.deep.equal(
+          expectedTrigger(project, 'user.delete')
+        );
+
+        expect(cloudFunction.__endpoint).to.deep.equal(
+          expectedEndpoint(project, 'user.delete')
+        );
       });
     });
 
@@ -198,6 +230,11 @@ describe('Auth Functions', () => {
         const cloudFunction = functions.handler.auth.user.onCreate(() => null);
         expect(cloudFunction.__trigger).to.deep.equal({});
       });
+
+      it('should return an empty endpoint', () => {
+        const cloudFunction = functions.handler.auth.user.onCreate(() => null);
+        expect(cloudFunction.__endpoint).to.be.undefined;
+      });
     });
 
     describe('#onDelete', () => {
@@ -206,13 +243,15 @@ describe('Auth Functions', () => {
       );
 
       it('should return an empty trigger', () => {
-        const handler = (user: firebase.auth.UserRecord) => {
-          return Promise.resolve();
-        };
-        const cloudFunction = functions.handler.auth.user.onDelete(handler);
+        const cloudFunction = functions.handler.auth.user.onDelete(() => null);
         expect(cloudFunction.__trigger).to.deep.equal({});
       });
 
+      it('should return an empty endpoint', () => {
+        const cloudFunction = functions.handler.auth.user.onDelete(() => null);
+        expect(cloudFunction.__endpoint).to.be.undefined;
+      });
+
       it('should handle wire format as of v5.0.0 of firebase-admin', () => {
         return cloudFunctionDelete(event.data, event.context).then(
           (data: any) => {
@@ -237,6 +276,10 @@ describe('Auth Functions', () => {
       expect(() => auth.user().onCreate(() => null).__trigger).to.throw(Error);
     });
 
+    it('should throw when endpoint is accessed', () => {
+      expect(() => auth.user().onCreate(() => null).__endpoint).to.throw(Error);
+    });
+
     it('should not throw when #run is called', () => {
       const cf = auth.user().onCreate(() => null);
       expect(cf.run).to.not.throw(Error);