Docs Updates (#70)

* Added new section in README.md to clarify how to do local testing of event functions.

* Updated wording

* fix: Fix docs gitignore

* docs: Fix and test sample code for Pub/Sub emulation.

Author: grant

docs/README.md

@@ -2,6 +2,8 @@
 
 This directory contains advanced docs around the Functions Framework.
 
+- [Testing events and Pub/Sub](events.md)
+- [Debugging Functions](debugging.md)
 - [Running and Deploying Docker Containers](docker.md)
 
 ## TODO Docs

docs/debugging.md

@@ -0,0 +1,31 @@
+## Debugging Functions
+
+The Functions Framework works with standard tooling that you might use when writing a function for a Node.js environment. You can attach a debugger to your function by following these steps.
+
+1. Write an `index.js` file containing your Node.js function:
+
+```js
+exports.helloWorld = (req, res) => {
+  res.send('Hello, World');
+};
+```
+
+2. Install the Functions Framework:
+
+```sh
+npm install @google-cloud/functions-framework
+```
+
+3. Run `node`, enable the inspector and run the Functions Framework:
+
+```sh
+node --inspect node_modules/@google-cloud/functions-framework --target=helloWorld
+...
+Debugger listening on ws://127.0.0.1:9229/5f57f5e9-ea4b-43ce-be1d-6e9b838ade4a
+For help see https://nodejs.org/en/docs/inspector
+Serving function...
+Function: helloWorld
+URL: http://localhost:8080/
+```
+
+You can now use an IDE or other tooling to add breakpoints, step through your code and debug your function.

docs/events.md

@@ -0,0 +1,77 @@
+## Local Testing of Cloud Events
+
+The setup for cloud functions that accept events is very similar to the instructions in the quickstart, with the following adjustments:
+
+In your `package.json`, add a signature type (in bold) to your start command:
+
+<pre>
+  "scripts": {
+    "start": "functions-framework --target=helloWorld <b>--signature-type=event"</b>
+  }
+</pre>
+
+Upon running ```sh npm start ```, you'll see the function is still being served at `http://localhost:8080/`. However, it is no longer accessible via GET requests from the browser. Instead, send a POST request where the request body conforms to the API defined by [push subscriptions](https://cloud.google.com/pubsub/docs/push). 
+
+### Submitting POST Request to Simulate Pub/Sub messages
+
+Create a `mockPubsub.json` file with the following contents:
+
+```json
+{
+  "message": {
+    "attributes": {
+      "key": "value"
+    },
+    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
+    "messageId": "136969346945"
+  },
+  "subscription": "projects/myproject/subscriptions/mysubscription"
+}
+```
+
+The file can be in any folder on your computer. From the terminal, go to the directory where `mockPubsub.json` is located, and run the following command (assuming your cloud function is hosted locally on port 8080):
+
+```sh 
+curl -d "@mockPubsub.json" \
+  -X POST \
+  -H "Ce-Type: true" \
+  -H "Ce-Specversion: true" \
+  -H "Ce-Source: true" \
+  -H "Ce-Id: true" \
+  http://localhost:8080
+```
+ 
+### Using the Pub/Sub emulator
+
+Another way to test your cloud function Pub/Sub endpoint is to use the [Pub/Sub Emulator](https://cloud.google.com/pubsub/docs/emulator). This allows you to use the Pub/Sub notification from another service to trigger your cloud function.
+
+The high level approach is to:
+1. Start the Pub/Sub Emulator
+2. Use the Pub/Sub client library to create a subscription and set the `pushEndpoint` to `http://localhost:8080`.
+
+After setup, all notifications to the subscription topic will be pushed to your cloud function.
+
+Here is a sample script for creating subscription with a `pushEndpoint`:
+
+ ```js
+const { PubSub } = require('@google-cloud/pubsub');
+
+async function main() {
+  const apiEndpoint = 'localhost:8085';
+  console.log(`Listening to the Pub/Sub emulator event at: ${apiEndpoint}`);
+  const pubsub = new PubSub({
+    apiEndpoint, // Pub/Sub emulator endpoint
+    projectId: 'myproject',
+  });
+  const topic = await pubsub.topic('my-topic');
+  const [topicExists] = await topic.exists();
+  if (!topicExists) {
+    await topic.create();
+  }
+  const createSubscriptionResponse = await topic.createSubscription('my_subscription', {
+    pushEndpoint: 'https://localhost:8080',
+  });
+}
+
+main();
+ ```