[azeventhubs] readme and more tests

sdk/messaging/azeventhubs/CHANGELOG.md

@@ -1,5 +1,5 @@
 # Release History
 
-## 0.1.0 (TBD)
+## 0.1.0 (2022-08-11)
 
 - Initial preview for the new version of the Azure Event Hubs Go SDK. 

sdk/messaging/azeventhubs/README.md

@@ -0,0 +1,133 @@
+# Azure Event Hubs Client Module for Go
+
+[Azure Event Hubs](https://azure.microsoft.com/services/event-hubs/) is a big data streaming platform and event ingestion service from Microsoft. For more information about Event Hubs see: [link](https://docs.microsoft.com/azure/event-hubs/event-hubs-about).
+
+Use the client library `github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs` in your application to:
+
+- Send messages to an event hub.
+- Consume messages from an event hub.
+
+**NOTE**: This library is currently a beta. There may be breaking changes until it reaches semantic version `v1.0.0`.
+
+Key links:
+- [Source code][source]
+- [API Reference Documentation][godoc]
+- [Product documentation](https://azure.microsoft.com/services/event-hubs/)
+- [Samples][godoc_examples]
+
+## Getting started
+
+### Install the package
+
+Install the Azure Event Hubs client module for Go with `go get`:
+
+```bash
+go get github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs
+```
+
+### Prerequisites
+
+- Go, version 1.18 or higher
+- An [Azure subscription](https://azure.microsoft.com/free/)
+- An [Event Hub namespace](https://docs.microsoft.com/azure/event-hubs/).
+- An Event Hub. You can create an event hub in your Event Hubs Namespace using the [Azure Portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-create), or the [Azure CLI](https://docs.microsoft.com/azure/event-hubs/event-hubs-quickstart-cli).
+
+### Authenticate the client
+
+Event Hub clients are created using an Event Hub a credential from the [Azure Identity package][azure_identity_pkg], like [DefaultAzureCredential][default_azure_credential].
+You can also create a client using a connection string.
+
+#### Using a service principal
+ - ConsumerClient: [link](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#example-NewConsumerClient)
+ - ProducerClient: [link](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#example-NewProducerClient)
+
+#### Using a connection string
+ - ConsumerClient: [link](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#example-NewConsumerClientFromConnectionString)
+ - ProducerClient: [link](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#example-NewProducerClientFromConnectionString)
+
+# Key concepts
+
+An Event Hub [**namespace**](https://docs.microsoft.com/azure/event-hubs/event-hubs-features#namespace) can have multiple event hubs. Each event hub, in turn, contains [**partitions**](https://docs.microsoft.com/azure/event-hubs/event-hubs-features#partitions) which store events.
+
+Events are published to an event hub using an [event publisher](https://docs.microsoft.com/azure/event-hubs/event-hubs-features#event-publishers). In this package, the event publisher is the [ProducerClient](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#ProducerClient)
+
+Events can be consumed from an event hub using an [event consumer](https://docs.microsoft.com/azure/event-hubs/event-hubs-features#event-consumers). In this package, the event consumer is the  [ConsumerClient](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#ConsumerClient). 
+
+For more information about Event Hubs features and terminology can be found here: [link](https://docs.microsoft.com/azure/event-hubs/event-hubs-features)
+
+# Examples
+
+Examples for various scenarios can be found on [pkg.go.dev](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#pkg-examples) or in the example*_test.go files in our GitHub repo for [azeventhubs](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/messaging/azeventhubs).
+
+# Troubleshooting
+
+### Logging
+
+This module uses the classification-based logging implementation in `azcore`. To enable console logging for all SDK modules, set the environment variable `AZURE_SDK_GO_LOGGING` to `all`. 
+
+Use the `azcore/log` package to control log event output or to enable logs for `azservicebus` only. For example:
+
+```go
+import (
+  "fmt"
+  azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
+)
+
+// print log output to stdout
+azlog.SetListener(func(event azlog.Event, s string) {
+    fmt.Printf("[%s] %s\n", event, s)
+})
+
+// pick the set of events to log
+azlog.SetEvents(
+  azeventhubs.EventConn,
+  azeventhubs.EventAuth,
+  azeventhubs.EventProducer,
+  azeventhubs.EventConsumer,
+)
+```
+
+## Contributing
+For details on contributing to this repository, see the [contributing guide][azure_sdk_for_go_contributing].
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+### Additional Helpful Links for Contributors  
+Many people all over the world have helped make this project better.  You'll want to check out:
+
+* [What are some good first issues for new contributors to the repo?](https://github.com/azure/azure-sdk-for-go/issues?q=is%3Aopen+is%3Aissue+label%3A%22up+for+grabs%22)
+* [How to build and test your change][azure_sdk_for_go_contributing_developer_guide]
+* [How you can make a change happen!][azure_sdk_for_go_contributing_pull_requests]
+* Frequently Asked Questions (FAQ) and Conceptual Topics in the detailed [Azure SDK for Go wiki](https://github.com/azure/azure-sdk-for-go/wiki).
+
+<!-- ### Community-->
+### Reporting security issues and security bugs
+
+Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).
+
+### License
+
+Azure SDK for Go is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/messaging/azeventhubs/LICENSE.txt) license.
+
+<!-- LINKS -->
+[azure_sdk_for_go_contributing]: https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md
+[azure_sdk_for_go_contributing_developer_guide]: https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md#developer-guide
+[azure_sdk_for_go_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md#pull-requests
+
+[azure_identity_pkg]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[default_azure_credential]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#NewDefaultAzureCredential
+[source]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/messaging/azeventhubs
+[godoc]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs
+[godoc_examples]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs#pkg-examples
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-go%2Fsdk%2Fmessaging%2Fazeventhubs%2FREADME.png)

sdk/messaging/azeventhubs/event_data_batch.go

@@ -5,14 +5,17 @@ package azeventhubs
 
 import (
 	"errors"
+	"fmt"
 	"sync"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/internal/uuid"
+	"github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs/internal"
+	"github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs/internal/amqpwrap"
 	"github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs/internal/go-amqp"
 )
 
-// ErrMessageTooLarge is returned when a message cannot fit into a batch when using MessageBatch.Add()
-var ErrMessageTooLarge = errors.New("the message could not be added because it is too large for the batch")
+// ErrEventDataTooLarge is returned when a message cannot fit into a batch when using EventDataBatch.AddEventData()
+var ErrEventDataTooLarge = errors.New("the EventData could not be added because it is too large for the batch")
 
 type (
 	// EventDataBatch represents a batch of messages to send to Event Hubs in a single message
@@ -126,7 +129,7 @@ func (mb *EventDataBatch) addAMQPMessage(msg *amqp.Message) error {
 			mb.batchEnvelope = nil
 		}
 
-		return ErrMessageTooLarge
+		return ErrEventDataTooLarge
 	}
 
 	mb.currentSize += actualPayloadSize
@@ -166,3 +169,35 @@ func calcActualSizeForPayload(payload []byte) uint64 {
 
 	return uint64(vbin32Overhead + len(payload))
 }
+
+func newEventDataBatch(sender amqpwrap.AMQPSenderCloser, options *NewEventDataBatchOptions) (*EventDataBatch, error) {
+	if options == nil {
+		options = &NewEventDataBatchOptions{}
+	}
+
+	if options.PartitionID != nil && options.PartitionKey != nil {
+		return nil, errors.New("either PartitionID or PartitionKey can be set, but not both")
+	}
+
+	var batch EventDataBatch
+
+	if options.PartitionID != nil {
+		// they want to send to a particular partition. The batch size should be the same for any
+		// link but we might as well use the one they're going to send to.
+		batch.partitionID = options.PartitionID
+	} else if options.PartitionKey != nil {
+		batch.partitionKey = options.PartitionKey
+	}
+
+	if options.MaxBytes == 0 {
+		batch.maxBytes = sender.MaxMessageSize()
+		return &batch, nil
+	}
+
+	if options.MaxBytes > sender.MaxMessageSize() {
+		return nil, internal.NewErrNonRetriable(fmt.Sprintf("maximum message size for batch was set to %d bytes, which is larger than the maximum size allowed by link (%d)", options.MaxBytes, sender.MaxMessageSize()))
+	}
+
+	batch.maxBytes = options.MaxBytes
+	return &batch, nil
+}