First version for API documentation (#57)

Gsantomaggio · web-flow · commit ef798d353578 · 2024-09-16T14:44:58.000+02:00
* First version for API documentation
* Refactor ci files name
---------
Signed-off-by: Gabriele Santomaggio &lt;G.santomaggio@gmail.com&gt;
diff --git a/.github/workflows/trigger_build-and-test.yaml b/.github/workflows/trigger_build-and-test.yaml
@@ -1,4 +1,4 @@
-name: rabbitmq-amqp-dotnet-client
+name: Trigger build and test  
 
 on:
   push:
@@ -8,4 +8,4 @@ on:
 
 jobs:
   call-build-test:
-    uses: ./.github/workflows/build-test.yaml
+    uses: ./.github/workflows/wf_build-and-test.yaml
diff --git a/.github/workflows/trigger_gh-pages.yaml b/.github/workflows/trigger_gh-pages.yaml
@@ -0,0 +1,9 @@
+name: Trigger github pages  
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  call-gh-pages:
+    uses: ./.github/workflows/wf_gh-pages.yaml
diff --git a/.github/workflows/trigger_publish.yaml b/.github/workflows/trigger_publish.yaml
@@ -1,4 +1,4 @@
-name: publish rabbitmq-dotnet-client
+name: Trigger publish the client to nuget
 
 on:
   release:
@@ -8,8 +8,8 @@ on:
 
 jobs:
   call-build-test:
-    uses: ./.github/workflows/build-test.yaml
+    uses: ./.github/workflows/wf_build-and-test.yaml
   call-publish-nuget:
-    uses: ./.github/workflows/publish-nuget.yaml
+    uses: ./.github/workflows/wf_publish-nuget.yaml
     needs: call-build-test
     secrets: inherit
diff --git a/.github/workflows/wf_build-and-test.yaml b/.github/workflows/wf_build-and-test.yaml
@@ -1,4 +1,4 @@
-name: Test against supported .NET
+name: Workflow test against supported .NET
 
 on:
   - workflow_call
@@ -34,7 +34,7 @@ jobs:
         id: install-start-rabbitmq
         run: ${{ github.workspace }}\.ci\windows\gha-setup.ps1
       - name: Test
-        timeout-minutes: 15
+        timeout-minutes: 20
         run: dotnet test ${{ github.workspace }}\Build.csproj --no-restore --no-build --logger 'console;verbosity=detailed'
       - name: Check for errors in RabbitMQ logs
         run: ${{ github.workspace }}\.ci\windows\gha-log-check.ps1
diff --git a/.github/workflows/wf_gh-pages.yaml b/.github/workflows/wf_gh-pages.yaml
@@ -0,0 +1,45 @@
+name: Workflow github pages 
+
+# Your GitHub workflow file under .github/workflows/
+# Trigger the action on push to main
+on:
+  - workflow_call
+
+    
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+  
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: 8.x
+
+    - run: dotnet tool update -g docfx
+    - run: docfx docfx.json
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: '_site'
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
diff --git a/.github/workflows/wf_publish-nuget.yaml b/.github/workflows/wf_publish-nuget.yaml
@@ -1,4 +1,4 @@
-name: publish-nuget
+name: Workflow publish the client to nuget
 
 on:
   workflow_call:
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # RabbitMQ AMQP 1.0 .NET Client
 
-This library is in early stages of development. It is meant to be used with RabbitMQ 4.0.
+This library is meant to be used with RabbitMQ 4.0.
+Still work in progress suitable for testing in pre-production environments
 
 ## How to Run
 
@@ -16,26 +17,6 @@ You can find an example in: `docs/Examples/GettingStarted`
 
 The client is distributed via [NuGet](https://www.nuget.org/packages/RabbitMQ.AMQP.Client/).
 
-## TODO
-
-- [x] Declare queues
-- [x] Declare exchanges
-- [x] Declare bindings
-- [x] Simple Publish messages
-- [x] Implement backpressure (it is implemented with MaxInflightMessages `MaxInFlight(2000).`)
-- [x] Simple Consume messages
-- [x] Recovery connection on connection lost
-- [x] Recovery management on connection lost
-- [x] Recovery queues on connection lost
-- [x] Recovery publishers on connection lost
-- [x] Recovery consumers on connection lost
-- [x] Implement Environment to manage the connections
-- [x] Complete the consumer part with `pause` and `unpause`
-- [x] Complete the binding/unbinding with the special characters
-- [x] Complete the queues/exchanges name with the special characters
-- [ ] Implement metrics ( See `System.Diagnostics.DiagnosticSource` [Link](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics-instrumentation) )
-- [x] Recovery exchanges on connection lost
-- [x] Recovery bindings on connection lost
-- [ ] Docker image to test in LRE [not mandatory]
-- [ ] Check the TODO in the code
+## Documentation
 
+- [API](https://rabbitmq.github.io/rabbitmq-amqp-dotnet-client/api/RabbitMQ.AMQP.Client.html)
diff --git a/RabbitMQ.AMQP.Client/IEnvironment.cs b/RabbitMQ.AMQP.Client/IEnvironment.cs
@@ -25,6 +25,9 @@ public interface IEnvironment
         /// <returns>IConnection</returns>
         public Task<IConnection> CreateConnectionAsync();
 
+        /// <summary>
+        /// Get all connections.
+        /// </summary>
         public ReadOnlyCollection<IConnection> GetConnections();
 
         /// <summary>
diff --git a/RabbitMQ.AMQP.Client/IManagement.cs b/RabbitMQ.AMQP.Client/IManagement.cs
@@ -22,6 +22,11 @@ public PreconditionFailedException(string message) : base(message)
         }
     }
 
+    /// <summary>
+    /// IManagement interface and is responsible for managing the AMQP resources.
+    /// RabbitMQ uses AMQP end point: "/management" to manage the resources like queues, exchanges, and bindings.
+    /// The management endpoint works like an HTTP RPC endpoint where the client sends a request to the server.
+    /// </summary>
     public interface IManagement : ILifeCycle
     {
         IQueueSpecification Queue();
diff --git a/RabbitMQ.AMQP.Client/Impl/AmqpConnection.cs b/RabbitMQ.AMQP.Client/Impl/AmqpConnection.cs
@@ -18,7 +18,7 @@ namespace RabbitMQ.AMQP.Client.Impl
 {
     /// <summary>
     /// AmqpConnection is the concrete implementation of <see cref="IConnection"/>
-    /// It is a wrapper around the AMQP.Net Lite <see cref="Connection"/> class
+    /// It is a wrapper around the Microsoft AMQP.Net Lite <see cref="Connection"/> class
     /// </summary>
     public class AmqpConnection : AbstractLifeCycle, IConnection
     {
@@ -50,11 +50,23 @@ public class AmqpConnection : AbstractLifeCycle, IConnection
         private readonly TaskCompletionSource<bool> _connectionClosedTcs =
             new(TaskCreationOptions.RunContinuationsAsynchronously);
 
+
+        /// <summary>
+        /// Read-only collection of publishers.
+        /// See <see cref="IPublisher"/>
+        /// </summary>
+        /// <returns> All the active Publishers </returns>
         public ReadOnlyCollection<IPublisher> GetPublishers()
         {
             return Publishers.Values.ToList().AsReadOnly();
         }
 
+
+        /// <summary>
+        /// Read-only collection of consumers.
+        /// See <see cref="IConsumer"/>
+        /// </summary>
+        /// <returns> All the active Consumers </returns>
         public ReadOnlyCollection<IConsumer> GetConsumers()
         {
             return Consumers.Values.ToList().AsReadOnly();
@@ -77,6 +89,7 @@ await connection.OpenAsync()
             return connection;
         }
 
+
         public IManagement Management()
         {
             return _management;
diff --git a/RabbitMQ.AMQP.Client/Impl/AmqpManagement.cs b/RabbitMQ.AMQP.Client/Impl/AmqpManagement.cs
@@ -17,9 +17,8 @@
 namespace RabbitMQ.AMQP.Client.Impl
 {
     /// <summary>
-    /// AmqpManagement implements the IManagement interface and is responsible for managing the AMQP resources.
-    /// RabbitMQ uses AMQP end  point: "/management" to manage the resources like queues, exchanges, and bindings.
-    /// The management endpoint works like an HTTP RPC endpoint where the client sends a request to the server
+    /// AmqpManagement implements the IManagement
+    /// See <see cref="IManagement"/> for more information
     /// </summary>
     public class AmqpManagement : AbstractLifeCycle, IManagement, IManagementTopology
     {
@@ -55,23 +54,45 @@ internal AmqpManagement(AmqpManagementParameters amqpManagementParameters)
             _amqpManagementParameters = amqpManagementParameters;
         }
 
+        /// <summary>
+        /// Create a new queue specification
+        /// See <see cref="IQueueSpecification"/> for more information
+        /// </summary>
+        /// <returns> A builder for IQueueSpecification </returns>
         public IQueueSpecification Queue()
         {
             ThrowIfClosed();
             return new AmqpQueueSpecification(this);
         }
 
+        /// <summary>
+        /// Create a new queue specification with the given name
+        /// See <see cref="IQueueSpecification"/> for more information
+        /// </summary>
+        /// <returns>A builder for IQueueSpecification </returns>
         public IQueueSpecification Queue(string name)
         {
             return Queue().Name(name);
         }
 
+
+        /// <summary>
+        /// Get the queue info for the given queue specification
+        /// See <see cref="IQueueInfo"/> for more information
+        /// </summary>
+        /// <returns> Queue Information</returns>
         public Task<IQueueInfo> GetQueueInfoAsync(IQueueSpecification queueSpec,
             CancellationToken cancellationToken = default)
         {
             return GetQueueInfoAsync(queueSpec.QueueName, cancellationToken);
         }
 
+
+        /// <summary>
+        /// Get the queue info for the given queue name
+        /// See <see cref="IQueueInfo"/> for more information
+        /// </summary>
+        /// <returns> Queue Information</returns>
         public async Task<IQueueInfo> GetQueueInfoAsync(string queueName,
             CancellationToken cancellationToken = default)
         {
@@ -86,6 +107,7 @@ public async Task<IQueueInfo> GetQueueInfoAsync(string queueName,
             return new DefaultQueueInfo((Map)response.Body);
         }
 
+
         internal IQueueSpecification Queue(QueueSpec spec)
         {
             return Queue().Name(spec.QueueName)
@@ -94,12 +116,25 @@ internal IQueueSpecification Queue(QueueSpec spec)
                 .Arguments(spec.QueueArguments);
         }
 
+
+        /// <summary>
+        ///  Create a new AMQPExchange specification
+        ///  See <see cref="IExchangeSpecification"/> for more information
+        /// </summary>
+        /// <returns>A builder for IExchangeSpecification</returns>
         public IExchangeSpecification Exchange()
         {
             ThrowIfClosed();
             return new AmqpExchangeSpecification(this);
         }
 
+
+        /// <summary>
+        ///
+        /// Create a new AMQPExchange specification with the given name
+        /// See <see cref="IExchangeSpecification"/> for more information
+        /// </summary>
+        /// <returns> A builder for IExchangeSpecification</returns>
         public IExchangeSpecification Exchange(string name)
         {
             return Exchange().Name(name);
@@ -133,6 +168,9 @@ ITopologyListener IManagementTopology.TopologyListener()
             return _amqpManagementParameters.TopologyListener();
         }
 
+        /// <summary>
+        ///  Open the management session to RabbitMQ
+        /// </summary>
         public override async Task OpenAsync()
         {
             if (State == State.Open)
@@ -195,7 +233,8 @@ private async Task ProcessResponses()
                             // this is not a problem, it is just a timeout. 
                             // the timeout is set to 60 seconds. 
                             // For the moment I'd trace it at some point we can remove it
-                            Trace.WriteLine(TraceLevel.Verbose, $"Management:Timeout {timeout.Seconds} s.. waiting for message.");
+                            Trace.WriteLine(TraceLevel.Verbose,
+                                $"Management:Timeout {timeout.Seconds} s.. waiting for message.");
                             continue;
                         }
 
@@ -228,9 +267,11 @@ private async Task EnsureReceiverLinkAsync()
                     RcvSettleMode = ReceiverSettleMode.First,
                     Properties = new Fields { { new Symbol("paired"), true } },
                     LinkName = LinkPairName,
-                    Source = new Source() { Address = ManagementNodeAddress, ExpiryPolicy = new Symbol("LINK_DETACH"), },
+                    Source =
+                        new Source() { Address = ManagementNodeAddress, ExpiryPolicy = new Symbol("LINK_DETACH"), },
                     Handle = 1,
-                    Target = new Target() { Address = ManagementNodeAddress, ExpiryPolicy = new Symbol("SESSION_END"), },
+                    Target =
+                        new Target() { Address = ManagementNodeAddress, ExpiryPolicy = new Symbol("SESSION_END"), },
                 };
 
                 var tcs = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
@@ -334,13 +375,7 @@ internal Task<Message> RequestAsync(string id, object? body, string path, string
         {
             var message = new Message(body)
             {
-                Properties = new Properties
-                {
-                    MessageId = id,
-                    To = path,
-                    Subject = method,
-                    ReplyTo = ReplyTo
-                }
+                Properties = new Properties { MessageId = id, To = path, Subject = method, ReplyTo = ReplyTo }
             };
 
             return RequestAsync(message, expectedResponseCodes, timeout, cancellationToken);
@@ -462,7 +497,8 @@ protected virtual Task InternalSendAsync(Message message, TimeSpan timeout)
             if (_senderLink is null)
             {
                 // TODO create "internal bug" exception type?
-                throw new InvalidOperationException("_senderLink is null, report via https://github.com/rabbitmq/rabbitmq-amqp-dotnet-client/issues");
+                throw new InvalidOperationException(
+                    "_senderLink is null, report via https://github.com/rabbitmq/rabbitmq-amqp-dotnet-client/issues");
             }
 
             return _senderLink.SendAsync(message, timeout);
diff --git a/docfx.json b/docfx.json

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name: publish-nuget`
	`1`	`+name: Workflow publish the client to nuget`
`2`	`2`
`3`	`3`	`on:`
`4`	`4`	`workflow_call:`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,11 @@ public PreconditionFailedException(string message) : base(message)`
`22`	`22`	`}`
`23`	`23`	`}`
`24`	`24`
	`25`	`+ /// <summary>`
	`26`	`+ /// IManagement interface and is responsible for managing the AMQP resources.`
	`27`	`+ /// RabbitMQ uses AMQP end point: "/management" to manage the resources like queues, exchanges, and bindings.`
	`28`	`+ /// The management endpoint works like an HTTP RPC endpoint where the client sends a request to the server.`
	`29`	`+ /// </summary>`
`25`	`30`	`public interface IManagement : ILifeCycle`
`26`	`31`	`{`
`27`	`32`	`IQueueSpecification Queue();`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ namespace RabbitMQ.AMQP.Client.Impl`
`18`	`18`	`{`
`19`	`19`	`/// <summary>`
`20`	`20`	`/// AmqpConnection is the concrete implementation of <see cref="IConnection"/>`
`21`		`- /// It is a wrapper around the AMQP.Net Lite <see cref="Connection"/> class`
	`21`	`+ /// It is a wrapper around the Microsoft AMQP.Net Lite <see cref="Connection"/> class`
`22`	`22`	`/// </summary>`
`23`	`23`	`public class AmqpConnection : AbstractLifeCycle, IConnection`
`24`	`24`	`{`
`@@ -50,11 +50,23 @@ public class AmqpConnection : AbstractLifeCycle, IConnection`
`50`	`50`	`private readonly TaskCompletionSource<bool> _connectionClosedTcs =`
`51`	`51`	`new(TaskCreationOptions.RunContinuationsAsynchronously);`
`52`	`52`
	`53`	`+`
	`54`	`+ /// <summary>`
	`55`	`+ /// Read-only collection of publishers.`
	`56`	`+ /// See <see cref="IPublisher"/>`
	`57`	`+ /// </summary>`
	`58`	`+ /// <returns> All the active Publishers </returns>`
`53`	`59`	`public ReadOnlyCollection<IPublisher> GetPublishers()`
`54`	`60`	`{`
`55`	`61`	`return Publishers.Values.ToList().AsReadOnly();`
`56`	`62`	`}`
`57`	`63`
	`64`	`+`
	`65`	`+ /// <summary>`
	`66`	`+ /// Read-only collection of consumers.`
	`67`	`+ /// See <see cref="IConsumer"/>`
	`68`	`+ /// </summary>`
	`69`	`+ /// <returns> All the active Consumers </returns>`
`58`	`70`	`public ReadOnlyCollection<IConsumer> GetConsumers()`
`59`	`71`	`{`
`60`	`72`	`return Consumers.Values.ToList().AsReadOnly();`
`@@ -77,6 +89,7 @@ await connection.OpenAsync()`
`77`	`89`	`return connection;`
`78`	`90`	`}`
`79`	`91`
	`92`	`+`
`80`	`93`	`public IManagement Management()`
`81`	`94`	`{`
`82`	`95`	`return _management;`