chore: add firebase protobuf example (#417)

Author: kevmoo

.github/workflows/verify_examples.yml

@@ -18,13 +18,14 @@ jobs:
     strategy:
       matrix:
         example_directory:
-          - examples/hello
-          - examples/json
-          - examples/raw_cloudevent
-          - examples/fullstack/backend
           - dartfn/templates/cloudevent
           - dartfn/templates/helloworld
           - dartfn/templates/json
+          - examples/fullstack/backend
+          - examples/hello
+          - examples/json
+          - examples/protobuf_firestore
+          - examples/raw_cloudevent
     defaults:
       run:
         working-directory: ${{ matrix.example_directory }}

examples/protobuf_firestore/.dockerignore

@@ -0,0 +1,7 @@
+.dart_tool/
+.dockerignore
+.git/
+.github/
+.gitignore
+.idea/
+Dockerfile

examples/protobuf_firestore/.gitignore

@@ -0,0 +1,11 @@
+# See https://dart.dev/guides/libraries/private-files
+
+# Files and directories created by pub
+.dart_tool/
+pubspec.lock
+
+# Standard files for Cloud Functions conformance tests
+# https://github.com/GoogleCloudPlatform/functions-framework-conformance
+function_output.json
+serverlog_stderr.txt
+serverlog_stdout.txt

examples/protobuf_firestore/Dockerfile

@@ -0,0 +1,23 @@
+FROM dart:stable AS build
+
+# Resolve app dependencies.
+WORKDIR /app
+COPY pubspec.* ./
+RUN dart pub get
+
+# Copy app source code and AOT compile it.
+COPY . .
+# Ensure packages are still up-to-date if anything has changed
+RUN dart pub get --offline
+RUN dart pub run build_runner build --delete-conflicting-outputs
+RUN dart compile exe bin/server.dart -o bin/server
+
+# Build minimal serving image from AOT-compiled `/server` and required system
+# libraries and configuration files stored in `/runtime/` from the build stage.
+FROM scratch
+COPY --from=build /runtime/ /
+COPY --from=build /app/bin/server /app/bin/
+
+# Start server.
+EXPOSE 8080
+ENTRYPOINT ["/app/bin/server", "--signature-type=cloudevent"]

examples/protobuf_firestore/README.md

@@ -0,0 +1,118 @@
+# Basic CloudEvent example
+
+This example demonstrates writing a function to handle a CloudEvent.
+
+CloudEvent function handlers don't return a response to send to the event
+producer. They generally perform some work and print output for logging.
+
+The basic shape of the function handler looks like this:
+
+```dart
+@CloudFunction()
+void function(CloudEvent event, RequestContext context) {
+}
+```
+
+Or like this if it needs to perform work that will complete sometime in the
+future:
+
+```dart
+@CloudFunction()
+FutureOr<void> function(CloudEvent event, RequestContext context) async {
+}
+```
+
+The full code of the function for this example is shown below:
+
+lib/functions.dart
+
+```dart
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:functions_framework/functions_framework.dart';
+
+const _encoder = JsonEncoder.withIndent(' ');
+
+@CloudFunction()
+void function(CloudEvent event, RequestContext context) {
+  context.logger.info('event subject: ${event.subject}');
+  stderr.writeln(_encoder.convert(event));
+}
+```
+
+All the function does is log the source and subject of the CloudEvent that
+triggered it, and then prints out the entire event JSON object for informational
+purposes.
+
+## Generate project files
+
+The Dart `build_runner` tool generates `bin/server.dart`, the main entry point
+for the function server app, which invokes the function in `lib/functions.dart`.
+
+Run the `build_runner` tool, as shown here:
+
+```shell
+$ dart run build_runner build
+[INFO] Generating build script completed, took 337ms
+[INFO] Reading cached asset graph completed, took 48ms
+[INFO] Checking for updates since last build completed, took 426ms
+[INFO] Running build completed, took 13ms
+[INFO] Caching finalized dependency graph completed, took 29ms
+[INFO] Succeeded after 51ms with 0 outputs (0 actions)
+```
+
+## Test the function
+
+```shell
+$ dart test
+00:02 +1: All tests passed!
+```
+
+## Run the function
+
+The default signature type for a function is for handling normal HTTP requests.
+When running a function for handling a cloudevent, you must either set
+the `FUNCTION_SIGNATURE_TYPE` environment variable or the
+`--signature-type` command line option to `cloudevent`, as shown below:
+
+```shell
+$ dart run bin/server.dart --signature-type cloudevent
+Listening on :8080
+```
+
+From another terminal, trigger the CloudEvent by posting event data:
+
+```shell
+$ curl --data-binary @sample/data.json -H 'content-type: application/json' -w '%{http_code}\n' localhost:8080
+200
+```
+
+Tools like [curl] (and [postman]) are good for sending HTTP requests. The
+options used in this example are:
+
+- `--data-binary @sample/data.json` - set the request body to a JSON document
+  read from the file `sample/data.json`
+- `-H "content-type: application/json"` - set an HTTP header to indicate that
+  the body is a JSON document
+- `-w '%{http_code}\n'` - print the HTTP status code (expect 200 for success)
+
+Alternatively, instead of running `curl`, you can run either of the following
+Dart scripts examples under the `examples/raw_cloudevent/tool` directory:
+
+- `dart run tool/binary_mode_request.dart`
+- `dart run tool/structured_mode_request.dart`
+
+For more details on getting started or to see how to run the function locally on
+Docker or deploy to Cloud Run, see these quick start guides:
+
+- [Quickstart: Dart]
+- [Quickstart: Docker]
+- [Quickstart: Cloud Run]
+
+<!-- reference links -->
+[curl]: https://curl.se/docs/manual.html
+[Quickstart: Dart]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/docs/quickstarts/01-quickstart-dart.md
+[Quickstart: Docker]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/docs/quickstarts/02-quickstart-docker.md
+[Quickstart: Cloud Run]: https://github.com/GoogleCloudPlatform/functions-framework-dart/blob/main/docs/quickstarts/03-quickstart-cloudrun.md
+[postman]: https://www.postman.com/product/api-client/

examples/protobuf_firestore/bin/server.dart

@@ -0,0 +1,31 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:functions_framework/functions_framework.dart';
+
+import 'src/function_types.dart';
+
+@CloudFunction()
+void function(CloudEvent event, RequestContext context) {
+  context.logger.info('event subject: ${event.subject}');
+  context.logger.debug(jsonEncode(context.request.headers));
+  context.responseHeaders['x-data-runtime-types'] =
+      event.data.runtimeType.toString();
+
+  final instance = DocumentEventData.fromBuffer(event.data as List<int>);
+  stderr.writeln(jsonEncode(instance.toProto3Json()));
+}

examples/protobuf_firestore/lib/functions.dart

@@ -0,0 +1,3 @@
+export 'google/events/cloud/firestore/v1/data.pb.dart';
+export 'google/protobuf/struct.pbenum.dart' show NullValue;
+export 'google/protobuf/timestamp.pb.dart';

examples/protobuf_firestore/lib/src/function_types.dart

@@ -0,0 +1,5 @@
+# https://dart.dev/guides/language/analysis-options
+analyzer:
+  errors:
+    inference_failure_on_collection_literal: ignore
+    require_trailing_commas: ignore