feat: add googlepubsub bindings

This commit contains two bindings, a `Channel Binding Object` and a
`Message Binding Object` for Google Cloud Pub/Sub using the
`googlepubsub` protocol name.

CODEOWNERS

@@ -8,8 +8,9 @@
 
 * @derberg @fmvilas @asyncapi-bot-eve
 
-/anypointmq/ @GeraldLoeffler
-/ibmmq/      @rcoppen
-/kafka/      @lbroudoux @dalelane
-/solace/     @damaru-inc @CameronRushton
-*.json       @KhudaDad414
+/anypointmq/   @GeraldLoeffler
+/ibmmq/        @rcoppen
+/kafka/        @lbroudoux @dalelane
+/googlepubsub/ @whitlockjc
+/solace/       @damaru-inc @CameronRushton
+*.json         @KhudaDad414

README.md

@@ -6,6 +6,7 @@ This repository contains the specifications for each AsyncAPI protocol binding.
 
 * [AMQP binding](./amqp)
 * [AMQP 1.0 binding](./amqp1)
+* [Google Cloud Pub/Sub binding](./googlepubsub)
 * [HTTP binding](./http)
 * [IBM MQ binding](./ibmmq)
 * [JMS binding](./jms)

googlepubsub/README.md

@@ -0,0 +1,184 @@
+# Google Cloud Pub/Sub Bindings
+
+This document defines how to describe Google Cloud Pub/Sub specific information with AsyncAPI.
+
+<a name="version"></a>
+
+## Version
+
+Current version is `0.1.0`.
+
+<a name="channel"></a>
+
+## Channel Binding Object
+
+The `Channel Bindings Object` is used to describe the Google Cloud Pub/Sub specific
+[Topic](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create) details with AsyncAPI.
+
+Field Name | Type | Description
+---|---|---
+`bindingVersion`|String|The current version is `0.1.0`
+`labels`|Object|An object of key-value pairs _(These are used to categorize Cloud Resources like Cloud Pub/Sub Topics.)_
+`messageRetentionDuration`|String|Indicates the minimum duration to retain a message after it is published to the topic _(Must be a valid [Duration](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Duration).)_
+`messageStoragePolicy`|[Message Storage Policy Object](#message-storage-policy-object)|Policy constraining the set of Google Cloud Platform regions where messages published to the topic may be stored
+`schemaSettings`|[Schema Settings Object](#schema-settings-object)|Settings for validating messages published against a schema
+
+<a name="message-storage-policy-object"></a>
+
+### Message Storage Policy Object
+
+The `Message Storage Policy Object` is used to describe the Google Cloud Pub/Sub
+[MessageStoragePolicy](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#MessageStoragePolicy)
+Object with AsyncAPI.
+
+Field Name | Type | Description
+---|---|---
+`allowedPersistenceRegions`|String[]|A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage
+
+<a name="schema-settings-object"></a>
+
+### Schema Settings Object
+
+The `Schema Settings Object` is used to describe the Google Cloud Pub/Sub
+[SchemaSettings](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#SchemaSettings) Object with
+AsyncAPI.
+
+Field Name | Type | Description
+---|---|---
+`encoding`|String|The encoding of the message _(Must be one of the possible [Encoding](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#encoding) values.)_
+`firstRevisionId`|String|The minimum _(inclusive)_ revision allowed for validating messages
+`lastRevisionId`|String|The maximum _(inclusive)_ revision allowed for validating messages
+`name`|String|The name of the schema that messages published should be validated against _(Format is `projects/{project}/schemas/{schema}`.)_
+
+<a name="channel-binding-example"></a>
+
+### Example
+
+```yaml
+# ...
+channels:
+  projects/your-project/topics/topic-avro-schema:
+    bindings:
+      googlepubsub:
+        schemaSettings:
+          encoding: avro
+          name: projects/your-project/schemas/message-avro
+# ...
+  projects/jaydub-testing/topics/messages-proto-schema:
+    bindings:
+      googlepubsub:
+        messageStoragePolicy:
+          allowedPersistenceRegions:
+          - us-central1
+          - us-central2
+          - us-east1
+          - us-east4
+          - us-east5
+          - us-east7
+          - us-south1
+          - us-west1
+          - us-west2
+          - us-west3
+          - us-west4
+        schemaSettings:
+          encoding: protobuf
+          name: projects/your-project/schemas/message-proto
+# ...
+```
+
+<a name="message"></a>
+
+## Message Binding Object
+
+The `Message Binding Object` is used to describe the Google Cloud Pub/Sub specific
+[PubsubMessage](https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage) details, alongside with pertintent
+parts of the Google Cloud Pub/Sub
+[Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema)
+Object, with AsyncAPI.
+
+Field Name | Type | Description
+---|---|---
+`bindingVersion`|String|The current version is `0.1.0`
+`attributes`|Object|An object of key-value pairs _(Attributes for this message.)_
+`orderingKey`|String|if non-empty, identifies related messages for which publish order should be respected
+`schema`|[Schema Definition Object](#schema-definition-object)|Describes the schema used to validate the payload of this message
+
+<a name="schema-definition-object"></a>
+
+### Schema Definition Object
+
+The `Schema Definition Object` is used to describe the Google Cloud Pub/Sub
+[Schema]([Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema)) Object with AsyncAPI.
+While some of this information could be, or is, described using native AsyncAPI, for consistency it makes sense to
+provide this information here at all times, especially for cases where AsyncAPI does not natively support describing
+payloads using a supported Google Cloud Pub/Sub schema format like Protobuf.
+
+Field Name | Type | Description
+---|---|---
+`definition`|String|The definition of the schema
+`name`|String|The name of the schema
+`type`|String|The type of the schema
+
+<a name="message-binding-example"></a>
+
+### Example
+
+```yaml
+# ...
+components:
+  messages:
+    messageAvroAsJSON:
+      bindings:
+        googlepubsub:
+          schema:
+            definition: |
+              {
+                "type" : "record",
+                "name" : "Message",
+                "fields" : [
+                  {
+                    "name" : "message",
+                    "type" : "string"
+                  }
+                ]
+              }
+            name: projects/your-project/schemas/message-avro
+            type: avro
+      contentType: application/json
+      name: projects/your-project/schemas/message-avro
+      payload:
+        fields:
+        - name: message
+          type: string
+        name: Message
+        type: record
+      schemaFormat: application/vnd.apache.avro+yaml;version=1.9.0
+    messageProto:
+      bindings:
+        googlepubsub:
+          schema:
+            definition: |
+              syntax = "proto2";
+
+              message Message {
+                required string message = 1;
+              }
+            name: projects/your-project/schemas/message-proto
+            type: protobuf
+      contentType: application/octet-stream
+      name: projects/your-project/schemas/message-proto
+      payload: true
+# ...
+```
+
+<a name="operation"></a>
+
+## Operation Binding Object
+
+This object MUST NOT contain any properties. Its name is reserved for future use.
+
+<a name="server"></a>
+
+## Server Binding Object
+
+This object MUST NOT contain any properties. Its name is reserved for future use.

googlepubsub/json_schemas/channel.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://asyncapi.com/bindings/amqp/channel.json",
+  "title": "Cloud Pub/Sub Channel Schema",
+  "description": "This object contains information about the channel representation for Google Cloud Pub/Sub.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-[\\w\\d\\.\\-\\_]+$": {
+      "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension"
+    }
+  },
+  "properties": {
+    "bindingVersion": {
+      "type": "string",
+      "enum": [
+        "0.1.0"
+      ],
+      "description": "The version of this binding."
+    },
+    "labels": {
+      "type": "object"
+    },
+    "messageRetentionDuration": {
+      "type": "string"
+    },
+    "messageStoragePolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowedPersistenceRegions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "schemaSettings": {
+      "type": "object",
+      "additionalItems": false,
+      "properties": {
+        "encoding": {
+          "type": "string"
+        },
+        "firstRevisionId": {
+          "type": "string"
+        },
+        "lastRevisionId": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": ["encoding", "name"]
+    }
+  },
+  "required": ["schemaSettings"],
+  "examples": [
+    {
+      "labels": {
+        "label1": "value1",
+        "label2": "value2"
+      },
+      "messageRetentionDuration": "7d",
+      "messageStoragePolicy": {
+        "allowedPersistenceRegions": [
+          "us-central1",
+          "us-east1"
+        ]
+      },
+      "schemaSettings": {
+        "encoding": "avro",
+        "schema": "projects/your-project-id/schemas/your-schema"
+      }
+    }
+  ]
+}

googlepubsub/json_schemas/message.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://asyncapi.com/bindings/amqp/channel.json",
+  "title": "Cloud Pub/Sub Channel Schema",
+  "description": "This object contains information about the message representation for Google Cloud Pub/Sub.",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-[\\w\\d\\.\\-\\_]+$": {
+      "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension"
+    }
+  },
+  "properties": {
+    "bindingVersion": {
+      "type": "string",
+      "enum": [
+        "0.1.0"
+      ],
+      "description": "The version of this binding."
+    },
+    "attributes": {
+      "type": "object"
+    },
+    "orderingKey": {
+      "type": "string"
+    },
+    "schema": {
+      "type": "object",
+      "additionalItems": false,
+      "properties": {
+        "definition": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        }
+      },
+      "required": ["definition", "name", "type"]
+    }
+  },
+  "examples": [
+    {
+      "schema": {
+        "definition": "{\n  \"type\" : \"record\",\n  \"name\" : \"Message\",\n  \"fields\" : [\n    {\n      \"name\" : \"message\",\n      \"type\" : \"string\"\n    }\n  ]\n}\n",
+        "name": "projects/your-project-id/schemas/your-avro-schema-id",
+        "type": "avro"
+      }
+    },
+    {
+      "schema": {
+        "definition": "syntax = \"proto2\";\n\nmessage Message {\n  required string message = 1;\n}\n",
+        "name": "projects/your-project-id/schemas/your-protobuf-schema-id",
+        "type": "protobuf"
+      }
+    }
+  ]
+}