From 4189d4ff9307aea781ea6b2a71ad40ad5ec13d72 Mon Sep 17 00:00:00 2001 From: ripark Date: Fri, 23 Sep 2022 16:25:34 -0700 Subject: [PATCH 1/3] Adding in a section about TCP connection sharing, which is an important (but understated) feature. --- sdk/messaging/azeventhubs/migrationguide.md | 44 +++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/sdk/messaging/azeventhubs/migrationguide.md b/sdk/messaging/azeventhubs/migrationguide.md index 84c183a9b971..f62091b8a2ac 100644 --- a/sdk/messaging/azeventhubs/migrationguide.md +++ b/sdk/messaging/azeventhubs/migrationguide.md @@ -2,6 +2,50 @@ This guide is intended to assist in the migration from the `azure-event-hubs-go` package to the latest beta releases (and eventual GA) of the `github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs`. +Our goal with this newest package was to export components that can be easily integrated into multiple styles of application, while still mapping close to the underlying resources for AMQP. This includes making TCP connection sharing simple (a must when multiplexing across multiple partitions), making batching boundaries more explicit and also integrating with the `azidentity` package, opening up a large number of authentication methods. + +These changes are described in more detail, below. + +### TCP connection sharing + +In AMQP there are is a concept of a connection and links. AMQP Connections are TCP connections. Links are a logical conduit within an AMQP connection and there are typically many of them but they use the same connection and do not require their own socket. + +The prior version of this package did not allow you to share an AMQP connection, which meant sending to multiple partitions would require a TCP connection per partition. If your application used more than a few partitions this could use up a scarce resource. + +In the newer version of the library we now share connections when you create a top-level client (ProducerClient or ConsumerClient). Each client owns a single TCP connection, and will share that connection for any activities, including when child clients (like PartitionClient) are created. If you want to split activity across multiple connections you can still do so as by creating multiple instances of ProducerClient or ConsumerClient. + +Some examples: + +```go +// consumerClient will own a TCP connection. +consumerClient, err := azeventhubs.NewConsumerClient(/* arguments elided for example */) + +// Close the TCP connection (and any child links) +defer consumerClient.Close(context.TODO()) + +// this call will lazily create a set of AMQP links using the consumerClient's TCP connection. +partClient0, err := consumerClient.NewPartitionClient("0") +defer partClient0.Close(context.TODO()) // will close the AMQP link, not the connection + +// this call will also lazily create a set of AMQP links using the consumerClient's TCP connection. +partClient1, err := consumerClient.NewPartitionClient("1") +defer partClient1.Close(context.TODO()) // will close the AMQP link, not the connection +``` + +```go +// will lazily create an AMQP connection +producerClient, err := azeventhubs.NewProducerClient(/* arguments elided for example */) + +// close the TCP connection (and any child links created for sending events) +defer producerClient.Close(context.TODO()) + +// these calls will lazily create a set of AMQP links using the producerClient's TCP connection. +producerClient.SendBatch(context.TODO(), eventDataBatchForPartition0, nil) +producerClient.SendBatch(context.TODO(), eventDataBatchForPartition1, nil) +``` + +This was not possible in the older package. + ## Clients The `Hub` type has been replaced by two types: From af076bf8dc772ab217c098680e224788a76c0565 Mon Sep 17 00:00:00 2001 From: ripark Date: Fri, 23 Sep 2022 16:32:48 -0700 Subject: [PATCH 2/3] syntax! --- sdk/messaging/azeventhubs/migrationguide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/messaging/azeventhubs/migrationguide.md b/sdk/messaging/azeventhubs/migrationguide.md index f62091b8a2ac..d89cec5d4d54 100644 --- a/sdk/messaging/azeventhubs/migrationguide.md +++ b/sdk/messaging/azeventhubs/migrationguide.md @@ -24,11 +24,11 @@ consumerClient, err := azeventhubs.NewConsumerClient(/* arguments elided for exa defer consumerClient.Close(context.TODO()) // this call will lazily create a set of AMQP links using the consumerClient's TCP connection. -partClient0, err := consumerClient.NewPartitionClient("0") +partClient0, err := consumerClient.NewPartitionClient("0", nil) defer partClient0.Close(context.TODO()) // will close the AMQP link, not the connection // this call will also lazily create a set of AMQP links using the consumerClient's TCP connection. -partClient1, err := consumerClient.NewPartitionClient("1") +partClient1, err := consumerClient.NewPartitionClient("1", nil) defer partClient1.Close(context.TODO()) // will close the AMQP link, not the connection ``` @@ -40,8 +40,8 @@ producerClient, err := azeventhubs.NewProducerClient(/* arguments elided for exa defer producerClient.Close(context.TODO()) // these calls will lazily create a set of AMQP links using the producerClient's TCP connection. -producerClient.SendBatch(context.TODO(), eventDataBatchForPartition0, nil) -producerClient.SendBatch(context.TODO(), eventDataBatchForPartition1, nil) +producerClient.SendEventBatch(context.TODO(), eventDataBatchForPartition0, nil) +producerClient.SendEventBatch(context.TODO(), eventDataBatchForPartition1, nil) ``` This was not possible in the older package. From f300a4efa4a4096480a7d2d6b6e7200764725924 Mon Sep 17 00:00:00 2001 From: Richard Park <51494936+richardpark-msft@users.noreply.github.com> Date: Thu, 29 Sep 2022 10:24:21 -0700 Subject: [PATCH 3/3] Some small rewording. --- sdk/messaging/azeventhubs/migrationguide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/messaging/azeventhubs/migrationguide.md b/sdk/messaging/azeventhubs/migrationguide.md index d89cec5d4d54..e728e6330559 100644 --- a/sdk/messaging/azeventhubs/migrationguide.md +++ b/sdk/messaging/azeventhubs/migrationguide.md @@ -10,9 +10,11 @@ These changes are described in more detail, below. In AMQP there are is a concept of a connection and links. AMQP Connections are TCP connections. Links are a logical conduit within an AMQP connection and there are typically many of them but they use the same connection and do not require their own socket. -The prior version of this package did not allow you to share an AMQP connection, which meant sending to multiple partitions would require a TCP connection per partition. If your application used more than a few partitions this could use up a scarce resource. +The prior version of this package did not allow you to share an AMQP connection when sending events, which meant sending to multiple partitions would require a TCP connection per partition. If your application used more than a few partitions this could use up a scarce resource. -In the newer version of the library we now share connections when you create a top-level client (ProducerClient or ConsumerClient). Each client owns a single TCP connection, and will share that connection for any activities, including when child clients (like PartitionClient) are created. If you want to split activity across multiple connections you can still do so as by creating multiple instances of ProducerClient or ConsumerClient. +In the newer version of the library each top-level client (ProducerClient or ConsumerClient) owns their own TCP connection. For instance, in ProducerClient, sending to separate partitions creates multiple links internally, but not multiple TCP connections. ConsumerClient works similarly - it has a single TCP connection and calling ConsumerClient.NewPartitionClient creates new links, but not new TCP connections. + +If you want to split activity across multiple TCP connections you can still do so by creating multiple instances of ProducerClient or ConsumerClient. Some examples: @@ -44,8 +46,6 @@ producerClient.SendEventBatch(context.TODO(), eventDataBatchForPartition0, nil) producerClient.SendEventBatch(context.TODO(), eventDataBatchForPartition1, nil) ``` -This was not possible in the older package. - ## Clients The `Hub` type has been replaced by two types: