[mock-hub] Initial mock event hubs package

eng/.docsettings.yml

@@ -120,6 +120,7 @@ known_content_issues:
   - ["sdk/eventhub/eventhubs-checkpointstore-blob/README.md",  "#1583"]
   - ["sdk/eventhub/event-processor-host/README.md",  "#1583"]
   - ["sdk/eventhub/README.md",  "#1583"]
+  - ["sdk/eventhub/mock-hub/README.md",  "#1583"]
   - ["sdk/eventhub/testhub/README.md",  "#1583"]
   - ["sdk/graphrbac/graph/README.md",  "#1583"]
   - ["sdk/keyvault/README.md",  "#1583"]

rush.json

@@ -482,6 +482,11 @@
       "projectFolder": "sdk/eventhub/event-processor-host",
       "versionPolicyName": "client"
     },
+    {
+      "packageName": "@azure/mock-hub",
+      "projectFolder": "sdk/eventhub/mock-hub",
+      "versionPolicyName": "utility"
+    },
     {
       "packageName": "testhub",
       "projectFolder": "sdk/eventhub/testhub",

sdk/core/core-amqp/package.json

@@ -79,7 +79,7 @@
     "is-buffer": "^2.0.3",
     "jssha": "^3.1.0",
     "process": "^0.11.10",
-    "rhea": "^1.0.21",
+    "rhea": "^1.0.24",
     "rhea-promise": "^1.1.0",
     "tslib": "^2.0.0",
     "url": "^0.11.0",

sdk/eventhub/mock-hub/License

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdk/eventhub/mock-hub/README.md

@@ -0,0 +1,48 @@
+## Mock Event Hubs service
+
+This package exposes a mock Event Hubs service for use in testing.
+
+Currently the mock service represents a single Event Hub within a namespace.
+
+### Goals
+
+This project was spun up for the following reasons:
+
+1. Avoid hitting the live service for tests.
+2. Deterministically trigger 'bad' service behavior.
+3. Simplify tests that rely on state. (populate events, change consumer groups/partition ids)
+4. Extend to support record & playback.
+
+Currently, the project only fulfills the 1st goal.
+It is possible to start this service locally either in a separate process or in the same process as
+the event-hubs tests and run the live tests against the local service instead.
+
+### How to use the service in Event Hubs live tests
+
+First, the `mock-hub` needs to be configured with a cert to support TLS.
+
+Next, the `event-hubs` unit-test scripts can be updated to start the mock event hubs service
+and run the live tests against the service using the `NODE_EXTRA_CA_CERTS` environment variable pointing to the CA that mock-hub's cert was signed with.
+
+### Next steps
+
+Here's a list of some features that would be helpful for the `event-hubs` live tests:
+
+- Support multiple Event Hubs.
+  This would allow us to create a new Event Hub for each test and let us run all our tests in parallel.
+
+- Expose listeners on mock service.
+  This could be useful so we don't need to perform as many steps as we do today for tests.
+  For instance, instead of sending events then creating a consumer to make sure those events were sent,
+  we could listen on the mock service so it can tell us if the messages were received.
+
+- Expose APIs to trigger errors.
+  For example, it would be useful to be able to tell the service to do something like 'send 5 messages then throw an error'.
+
+### Additional details
+
+Some details on what features the mock service supports can be found [here](design/features.md).
+
+Some details on the overal architecture of this project can be found [here](design/architecture.md).
+
+To see a quick example of how to start the mock service, look at [sample/ehSample.ts](sample/ehSample.ts).

sdk/eventhub/mock-hub/design/architecture.md

@@ -0,0 +1,58 @@
+## How does it work?
+
+### Local AMQP server
+
+The local AMQP server is used by the mock Event Hubs service
+to handle peer connections and message normalization.
+
+It's an event emitter that simplifies some of the AMQP dance e.g. responding to received messages.
+
+It currently supports the following configuration options:
+
+- port
+- max message size
+- idle timeout
+- max channels
+- max frame size
+- tlsOptions
+  - ca - certificate authority
+  - cert - certificate chain in PEM format.
+  - key - private key for certificate chain.
+  - pfx - private key and certificate chain.
+  - passphrase - secret used when creating PFX or private key.
+
+### Mock Event Hubs
+
+Handles all the business logic of reacting to messages and connection/link creation/tear-down.
+
+Has an instance of the AMQP server.
+In theory it could hold multiple AMQP server instances to support receiver redirect.
+
+Supports the following configuration options as instantiation:
+
+- partition count
+- name (event hub name)
+- list of consumer groups (\$default always supported)
+- connectionInactivityTimeoutInMs
+
+### Message Store
+
+This is the in-memory storage for any events the service receives.
+
+The MessageStore does 3 things:
+
+- Stores messages as MessageRecords that are associated with a partition id.
+- Can return partition properties.
+- Can return a message iterator for a given partitionId and start position.
+
+### Streaming Partition Sender
+
+This sender pushes messages to a client-side receiver.
+
+The streaming partition sender respects the starting event position.
+It also is smart enough to only send events when the client-side receiver
+has put credits on the link.
+
+It gets an AsyncIterableIterator from the `MessageStore` so anytime a new
+event is received by the service, the sender can immediately push it to
+the client-side receiver.