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.
asyncapi · Aug 18, 2022 · ec7d81c · ec7d81c
1 parent 0dcef46
commit ec7d81c
Show file tree

Hide file tree

Showing 5 changed files with 242 additions and 5 deletions.
diff --git a/CODEOWNERS b/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
diff --git a/README.md b/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)

diff --git a/googlepubsub/README.md b/googlepubsub/README.md
@@ -0,0 +1,96 @@
+# 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 `1.0.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 `1.0.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="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 `1.0.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="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.
diff --git a/googlepubsub/json_schemas/channel.json b/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": [
+        "1.0.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"
+      }
+    }
+  ]
+}
diff --git a/googlepubsub/json_schemas/message.json b/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": [
+        "1.0.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"
+      }
+    }
+  ]
+}