diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..2e2e02575 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,45 @@ +name: Docs + +on: + push: + branches: + - main +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: 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: + + github_pages: + + name: docfx + runs-on: ubuntu-latest + + steps: + + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup dotnet + uses: actions/setup-dotnet@v3 + with: + dotnet-version: '7.x' + + - run: dotnet tool update -g docfx + - run: docfx docs/docfx.json + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: docs/_site + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..b6af25f91 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,9 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ + diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 000000000..e8079a3be --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1,5 @@ +############### +# temp file # +############### +*.yml +.manifest diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 000000000..ab2633602 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,4 @@ +# API Documentation + +You can browse the latest NATS.NET V2 API Documentation here. +API Documentation is auto-generated using [DocFX](https://dotnet.github.io/docfx/). diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 000000000..1379faa8b --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,56 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ "**/*.csproj" ], + "src": "../src" + } + ], + "dest": "api", + "includePrivateMembers": false, + "disableGitFeatures": false, + "disableDefaultFilter": false, + "noRestore": false, + "namespaceLayout": "flattened", + "memberLayout": "samePage", + "allowCompilationErrors": false + } + ], + "build": { + "content": [ + { + "files": [ + "api/**.yml", + "api/index.md" + ] + }, + { + "files": [ + "documentation/**.md", + "documentation/**/toc.yml", + "toc.yml", + "*.md" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "output": "_site", + "globalMetadataFiles": [], + "fileMetadataFiles": [], + "template": [ + "default", + "modern", + "nats_template" + ], + "postProcessors": [], + "keepFileLink": false, + "disableGitFeatures": false + } +} diff --git a/docs/documentation/intro.md b/docs/documentation/intro.md new file mode 100644 index 000000000..9e8ed980c --- /dev/null +++ b/docs/documentation/intro.md @@ -0,0 +1,9 @@ +# NATS.NET V2 Client + +NATS.NET V2 Client is a .Net client for the Open Source [Connective Technology for Adaptive Edge & Distributed Systems - NATS](https://nats.io/)! +It's build on top of the modern .Net 6+ platform, taking advantage of all the high performance features and +asynchronous programming model. + +NATS.NET V2 Client, just like NATS, is Open Source as is this documentation. +Please [let us know](https://natsio.slack.com/channels/dotnet) if you have updates and/or suggestions for +these docs. You can also create a Pull Request using the Edit on GitHub link on each page. diff --git a/docs/documentation/pub-sub.md b/docs/documentation/pub-sub.md new file mode 100644 index 000000000..1d3a76a79 --- /dev/null +++ b/docs/documentation/pub-sub.md @@ -0,0 +1,22 @@ +# Publish-Subscribe Pattern + +NATS implements a publish-subscribe message distribution model for one-to-many communication. +A publisher sends a message on a subject and any active subscriber listening on that subject +receives the message. + +```csharp +await using var nats = new NatsConnection(); + +await using sub = await nats.SubscribeAsync("foo"); + +for (int i = 0; i < 10; i++) +{ + Console.WriteLine($" Publishing {i}..."); + await nats.PublishAsync("foo", i); +} + +await foreach (var msg in sub.Msgs.ReadAllAsync()) +{ + Console.WriteLine($"Received {msg.Subject}: {msg.Data}\n"); +} +``` diff --git a/docs/documentation/req-rep.md b/docs/documentation/req-rep.md new file mode 100644 index 000000000..1bed021c4 --- /dev/null +++ b/docs/documentation/req-rep.md @@ -0,0 +1,18 @@ +# Request-Reply Pattern + +Request-Reply is a common pattern in modern distributed systems. +A request is sent, and the application either waits on the response with a certain timeout, +or receives a response asynchronously. + +```csharp +await using var nats = new NatsConnection(); + +await using var replyHandle = await nats.ReplyAsync("math.double", x => +{ + Console.WriteLine($"Received request: {x}") + return $"Answer is: { 2 * x }"; +}); + +var reply = await nats.RequestAsync("math.double", 2); +Console.WriteLine($"Received reply: {reply}") +``` diff --git a/docs/documentation/toc.yml b/docs/documentation/toc.yml new file mode 100644 index 000000000..182fbd99e --- /dev/null +++ b/docs/documentation/toc.yml @@ -0,0 +1,11 @@ +- name: Introduction + href: intro.md + +- name: Publish-Subscribe + href: pub-sub.md + +- name: Request-Reply + href: req-rep.md + +- name: Updating Documentation + href: update-docs.md \ No newline at end of file diff --git a/docs/documentation/update-docs.md b/docs/documentation/update-docs.md new file mode 100644 index 000000000..7f33ae563 --- /dev/null +++ b/docs/documentation/update-docs.md @@ -0,0 +1,20 @@ +# Updating Documentation + +As well as being able to edit pages on GitHub, you can also edit and update this documentation, +view locally and submit a Pull Request to be included in this documentation site. + +## Runnig DocFX locally + +Clone the NATS.NET V2 repository, then run `docfx` local server to view this documentation site. +You mush have [DocFX installed](https://dotnet.github.io/docfx/): + +``` +dotnet tool update -g docfx +``` + +Generate API documentation and run local server: +``` +$ git clone https://github.com/nats-io/nats.net.v2.git +$ cd nats.net.v2/docs +$ docfx docfx.json --serve +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..a41d92ac0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,70 @@ +# NATS.NET V2 (Preview) + +The NATS.NET V2 client is in preview and not recommended for production use. +Codebase is still under heavy development and currently we only have implementations for [core NATS](https://docs.nats.io/nats-concepts/core-nats) features. + +Please test and provide feedback by visiting our [Slack channel](https://natsio.slack.com/channels/dotnet). + +## NATS.NET V2 Goals + +- Only support Async I/O +- Target latest .NET LTS Release (currently `net6.0`) + +## Packages + +- **NATS.Client.Core**: [core NATS](https://docs.nats.io/nats-concepts/core-nats) +- **NATS.Client.Hosting**: extension to configure DI container +- **NATS.Client.JetStream**: JetStream *not yet implemented* + +## Basic Usage + +[Download the latest](https://nats.io/download/) `nats-server` for your platform and run it without any arguments. `nats-server` will listen +on its default TCP port 4222. + +Given that we have a plain class `Bar`, we can publish and subscribe to our `nats-server` sending +and receiving `Bar` objects: + +```csharp +public record Bar +{ + public int Id { get; set; } + public string Name { get; set; } +} +``` + +Subscribe to all `bar` [related subjects](https://docs.nats.io/nats-concepts/subjects): +```csharp +await using var nats = new NatsConnection(); + +await using sub = await nats.SubscribeAsync("bar.>"); +await foreach (var msg in sub.Msgs.ReadAllAsync()) +{ + Console.WriteLine($"Received {msg.Subject}: {msg.Data}\n"); +} +``` + +Publish `Bar` objects to related `bar` [subjects](https://docs.nats.io/nats-concepts/subjects): +```csharp +await using var nats = new NatsConnection(); + +for (int i = 0; i < 10; i++) +{ + Console.WriteLine($" Publishing {i}..."); + await nats.PublishAsync($"bar.baz.{i}", new Bar { Id = i, Name = "Baz" }); +} +``` + +You should also hook your logger to `NatsConnection` to make sure all is working as expected or +to get help diagnosing any issues you might have: +```csharp +var options = NatsOptions.Default with { LoggerFactory = new MinimumConsoleLoggerFactory(LogLevel.Error) }; +await using var nats = new NatsConnection(options); +``` + +## Contributing + +- Run `dotnet format` at root directory of project in order to clear warnings that can be auto-formatted + +## Attribution + +This library is based on the excellent work in [Cysharp/AlterNats](https://github.com/Cysharp/AlterNats) diff --git a/docs/nats_template/favicon.ico b/docs/nats_template/favicon.ico new file mode 100644 index 000000000..9464855b4 Binary files /dev/null and b/docs/nats_template/favicon.ico differ diff --git a/docs/nats_template/logo.svg b/docs/nats_template/logo.svg new file mode 100644 index 000000000..950d0a2da --- /dev/null +++ b/docs/nats_template/logo.svg @@ -0,0 +1,5 @@ + + + + + \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 000000000..f9422ed9b --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,12 @@ +- name: Documentation + href: documentation/ + +- name: API + href: api/ + homepage: api/index.md + +- name: GitHub + href: https://github.com/nats-io/nats.net.v2 + +- name: Slack + href: https://natsio.slack.com/channels/dotnet diff --git a/src/NATS.Client.Core/Commands/DirectWriteCommand.cs b/src/NATS.Client.Core/Commands/DirectWriteCommand.cs index eb5528a10..433d20a37 100644 --- a/src/NATS.Client.Core/Commands/DirectWriteCommand.cs +++ b/src/NATS.Client.Core/Commands/DirectWriteCommand.cs @@ -4,7 +4,7 @@ namespace NATS.Client.Core.Commands; // public for optimize reusing -public sealed class DirectWriteCommand : ICommand +internal sealed class DirectWriteCommand : ICommand { private readonly byte[] _protocol; diff --git a/src/NATS.Client.Core/Internal/ISocketConnection.cs b/src/NATS.Client.Core/Internal/ISocketConnection.cs index 2575899df..6b7f7fecc 100644 --- a/src/NATS.Client.Core/Internal/ISocketConnection.cs +++ b/src/NATS.Client.Core/Internal/ISocketConnection.cs @@ -1,6 +1,6 @@ namespace NATS.Client.Core.Internal; -public interface ISocketConnection : IAsyncDisposable +internal interface ISocketConnection : IAsyncDisposable { public Task WaitForClosed { get; }