diff --git a/.github/workflows/manual-release.yml b/.github/workflows/manual-release.yml index 2056721..a53b73e 100644 --- a/.github/workflows/manual-release.yml +++ b/.github/workflows/manual-release.yml @@ -41,4 +41,4 @@ jobs: run: dotnet pack --configuration Release --no-restore --no-build --include-symbols -p:PackageVersion=${{ inputs.version }} --output ./nuget - name: Push Packages to GitHub NuGet - run: dotnet nuget push ./nuget/**/*.nupkg --api-key ${{secrets.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json + run: dotnet nuget push ./nuget/**/*.nupkg --skip-duplicate --api-key ${{secrets.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json diff --git a/README.md b/README.md index 62246e2..9065ae3 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ The libraries currently provided by the framework are the following: | **Deveel.Webhooks.Sender** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Sender?label=latest&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Sender) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Sender) | | **Deveel.Webhooks.Service** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Service?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Service) | [![GitHub](https://img.shields.io/static/v1?label=NuGet&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Service) | | **Deveel.Webhooks.MongoDb** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.MongoDb?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.MongoDb) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.MongoDb) | +| **Deveel.Webhooks.EntityFramework** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.EntityFramework?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.EntityFramework) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.EntityFramework) | | **Deveel.Webhooks.DynamicLinq** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.DynamicLinq?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.DynamicLinq) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.DynamicLinq) | | **Deveel.Webhooks.Receiver.AspNetCore** | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Receiver.AspNetCore?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Receiver.AspNetCore) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Receiver.AspNetCore) | @@ -54,11 +55,11 @@ While working on a .NET Core 3.1/.NET 5 _PaaS_ (_Platform-as-a-Service_) project * Microsoft's _experimental_ projects never implemented any capability of handling subscriptions, and eventually removing also the _sender_ capability, focusing exclusively on _receivers_ * Alternative implementations providing similar capabilities are embedded and organic part of larger frameworks (like [ASP.NET Boilerplate](https://github.com/aspnetboilerplate/aspnetboilerplate)), that would have forced me to adopt the the entirety of such frameworks, beyond my design intentions -## Usage Documentation +## Documentation -We would like to help you getting started with this framework and to eventually extend it: please refer to the **[Documentation](docs/README.md)** section that we have produced for you. +We would like to help you getting started with this framework and to eventually extend it: please refer to the **[Documentation](docs/README.md)** section, or to the **[Gitbook](https://deveel.gitbook.io/webhooks)** website that we have produced for you. -The easiest way to get started is to follow the **[Quick Start](docs/QUICKSTART.md)** guide, but you can also refer to the **[Frequently Asked Questions](docs/FAQS.md)** section to get answers to the most common questions. +The easiest way to get started is to follow the **[Getting Started](docs/getting-started/README.md)** guide, but you can also refer to the **[Frequently Asked Questions](docs/FAQS.md)** section to get answers to the most common questions. ## Simple Usage Example diff --git a/docs/README.md b/docs/README.md index a0bb323..9ba785f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,66 +1,23 @@ - - # Deveel Webhooks Documentation Here you can find a documentation of the `Deveel Webhooks` framework, to help you getting started with the libraries and functions that compose it and to understand how it works. +## Introduction -## Basic Concepts - -To set the domain model of the framework, we need to introduce some basic concepts that are used in the framework. - -| Topic | Description | -| ---------------------------------------------------- | ------------------------------------------ | -| **[Webhook](concept_webhook.md)** | What is it a 'Webhook' and why I need it? | -| **[Subscriptions](concept_webhook_subscription.md)** | How does a subscription to an event works? | -| **[Senders](concept_webhook_sender.md)** | What is a sender of webooks? | -| **[Receivers](concept_webhook_receiver.md)** | What is a receiver of webooks? | -| **[Notifications](concept_webhook_notification.md)** | What is a notification of events? | - -## Basic Usage - -The following tutorials will guide you through the basic usage of the framework, showing how to use the different components to send, receive and manage webhooks. - -| Topic | Description | -| ------------------------------------ ------------------- | --------------------------------------------------------------------- | -| **[Getting Started](getting_started.md)** | Getting started with `Deveel Webhooks` | -| **[Sending Webhooks](basic_usage_send.md)** | Manually sending webhooks (no subscriptions) | -| **[Subscription Management](basic_usage_management.md)** | Manage subscriptions to events (no sending) | -| **[Notify Webhooks](basic_usage_notify.md)** | Notify webhooks subscribers (management, transformations and sending) | -| **[Receiving Webhooks](basic_usage_receive.md)** | Receive webhooks from external sources | - -## Advanced Usage - -A more advanced usage of the framework is possible by implementing custom components that can be used to extend the framework functionalities. +The framework is composed by a set of libraries that can be used, at different degrees, to implement a system that allows applications to send and receive webhooks. -| Topic | Description | -| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| **[Filtering Subscriptions](advanced_usage_filters.md)** | Allow subscribers to filter webhooks on dynamic parameters | -| **[Custom Data Factories](advanced_usage_custom_datafactory.md)** | Implement a component that transforms event data | -| **[Custom Receivers](advanced_usage_custom_receiver.md)** | Implement parsers for receiving webhooks | -| **[Using MongoDB Data Layers](advanced_usage_mongodb.md)** | Use the MongoDB data layer for the persistence of the webhook information model | -| **[Using Entity Framework Data Layers](advanced_usage_ef.md)** | Use the Entity Framework data layer for the persistence of the webhook information model | +* **Sending Webhooks** - Using libraries of the framework you can send webhooks to receivers, based on your own logic and rules. +* **Receiving Webhooks** - The framework provides a set libraries implementing the capabilities for receiving webhooks from senders, reacting to events from external systems (such as Twilio, SendGrid, Facebook, etc.). +* **Notifications** - The framework provides a set of libraries that can be used to manage subscriptions to events, notify subscribing applications of events occurred in your system. -## Receivers +--- -The framework provides a set of libraries that can be used to receive webhooks from external sources. +Read more about this framework: -| Receiver | Description | -| ------------------------------------ | -------------------------------------------------- | -| **[Facebook](facebook_receiver.md)** | Receive webhooks from Facebook Messenger | -| **[SendGrid](sendgrid_receiver.md)** | Receive webhooks and emails from SendGrid | -| **[Twilio](twilio_receiver.md)** | Receive webhooks and SMS/WhatsApp messages from Twilio | \ No newline at end of file +| Topic | Description | +| ------ | ------------- | +| **[Concepts](concepts/README.md)** | A list of basic concepts used in the framework | +| **[Getting Started](getting_started.md)** | A quick guide to start using the framework | +| **[Sending Webhooks](send_webhooks.md)** | Sending webhooks messages to receivers | +| **[Receiving Webhooks](receivers/README.md)** | Receiving webhooks from senders | +| **[Notifications](notifications/README.md)** | Notify subscribing applications of events occurred in your system | diff --git a/docs/concepts/README.md b/docs/concepts/README.md new file mode 100644 index 0000000..f14a1cf --- /dev/null +++ b/docs/concepts/README.md @@ -0,0 +1,11 @@ +# Concepts + +The following concepts are used in this project: + +| Topic | Description | +| ------- | ------------- | +| **[Webhook](webhook.md)** | What is it a 'Webhook' and why I need it? | +| **[Subscriptions](webhook_subscription.md)** | How does a subscription to an event works? | +| **[Senders](webhook_sender.md)** | What is a sender of webooks? | +| **[Receivers](webhook_receiver.md)** | What is a receiver of webooks? | +| **[Notifications](webhook_notification.md)** | What is a notification of events? | diff --git a/docs/concept_webhook.md b/docs/concepts/webhook.md similarity index 89% rename from docs/concept_webhook.md rename to docs/concepts/webhook.md index f8123b1..4c89050 100644 --- a/docs/concept_webhook.md +++ b/docs/concepts/webhook.md @@ -1,21 +1,7 @@ - - # What is a Webhook? +Briefly, we can say that a webhook is the notification of an event that has occurred somewhere, and that is sent to a listening application that is interested in such event. + ## The Event Model If we consider the overall model of _processes_, where an activity is performed, and eventually preceding other activities, until a final result, we can define the _events_ as the triggers of such activities (eg. _something has occurred, and therefore we must perform some subsequent activities_). diff --git a/docs/concept_webook_subscription.md b/docs/concepts/webook_subscription.md similarity index 100% rename from docs/concept_webook_subscription.md rename to docs/concepts/webook_subscription.md diff --git a/docs/getting_started.md b/docs/getting-started.md similarity index 93% rename from docs/getting_started.md rename to docs/getting-started.md index a560013..f6d2e7f 100644 --- a/docs/getting_started.md +++ b/docs/getting-started.md @@ -1,19 +1,3 @@ - - # Getting Started The overall design of this framework is open and extensible (implementing the traditional [Open-Closed Principle](https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle)), that means base contracts can be extended, composed or replaced. @@ -24,7 +8,7 @@ It is possible to use its components as they are provided, or use the base contr The overall set of libraries are available through [NuGet](https://nuget.org), and can be installed and restored easily once configured in your projects. -At the moment (_May 2023_) they are developed as `.NET 6.0` and thus compatible with all the profiles of the .NET framework greater or equal than this. +At the moment (_November 2023_) they are developed as `.NET 6.0` and thus compatible with all the profiles of the .NET framework greater or equal than this. The core library of the framework is `Deveel.Webhooks` and can be installed through the `dotnet` tool command line @@ -44,7 +28,7 @@ Or by editing your `.csproj` file and adding a `` entry. - + ... diff --git a/docs/notifications/README.md b/docs/notifications/README.md new file mode 100644 index 0000000..68ef8b9 --- /dev/null +++ b/docs/notifications/README.md @@ -0,0 +1,5 @@ +# Webhook Notifications + +The notification process of a webhook introduces elements of automation, putting together the _[subscription management](webhook_subscription_management.md)_ and the _[sending of webhooks](../sending-webhooks/README.md)_ processes, and an optional step of _[data transformation](custom_datafactory.md)_ (to resolve event information in a full formed object to be transferred). + +The _Deveel Webhook_ framework implements these functions through an instance of the `IWebhookNotifier` service, that uses a `IWebhookSubscriptionResolver` and the `IWebhookSender` instance configured. diff --git a/docs/advanced_usage_custom_datafactory.md b/docs/notifications/custom_datafactory.md similarity index 89% rename from docs/advanced_usage_custom_datafactory.md rename to docs/notifications/custom_datafactory.md index 42acba3..60dbec5 100644 --- a/docs/advanced_usage_custom_datafactory.md +++ b/docs/notifications/custom_datafactory.md @@ -1,19 +1,3 @@ - - # Producing Custom Data Factories In automated scenarios of notification, when an event triggers a process of construction of the webhooks and their delivery to subscribers, there could be a need to _transform_ the original data carried by those triggering events. diff --git a/docs/basic_usage_notification.md b/docs/notifications/webhook_notifier.md similarity index 67% rename from docs/basic_usage_notification.md rename to docs/notifications/webhook_notifier.md index 9452cdf..18216ea 100644 --- a/docs/basic_usage_notification.md +++ b/docs/notifications/webhook_notifier.md @@ -1,30 +1,10 @@ - - -# Webhook Notifications - -The notification process of a webhook introduces elements of automation, putting together the _[subscription management](basic_usage_management.md)_ and the _[sending of webhooks](basic_usage_send.md)_ processes, and an optional _[data transformation](advanced_usage_custom_datafactory.md)_ process (to resolve event information in a full formed object to be transferred). - -The _Deveel Webhook_ framework implements these functions through an instance of the `IWebhookNotifier` service, that uses a `IWebhookSubscriptionResolver` (by default backed by the subscription manager) and the `IWebhookSender` instance configured. - -Although the design of the framework allows the implementation of a custom `IWebhookNotifier`, a default implementation of the notifier service is provided through the `WebhookNotifier` class, that executes the following steps: - -1. The service firsts tries to resolve any webhook subscription matching the event type and the tenant identifier. -2. Subsequently the service tries to resolve any transformers (as `IWebhookDataFactory`) and trasnforms the event data into a new form. -3. All the matching subscriptions are iterated and a webhook is constructed for each of them, using the event information, the subscription and the event data (or the result of a transformation, if any happened) +# WebhookNotifier + +An default implementation of the `IWebhookNotifier` service is provided by the framework, as the `WebhookNotifier` class, that executes the following steps: + +1. The service firsts tries to resolve any webhook subscriptions matching the _event type_ and the _tenant identifier_ (_in case of multi-tenant scenarios_). +2. Tries to resolve any service implementing `IWebhookDataFactory`, and trasnforms the event data into a new form (eg. _resolving a database record from an identifier_) +3. All the matching subscriptions are iterated and a webhook object is constructed for each of them, using the _event metdata_ (eg. timestamp, stream name, type, etc.), the _subscription data_ and the _event data_ (or the result of a transformation, if any happened in the previous step) 4. The webhook object is matched against the subscription as follows: a. Not active subscriptions are skipped and will not be notified b. If the subscription includes any filter, these ones are matched against the webhook object formed in the previous steps, to determine if the conditions defined by the subscription are met @@ -54,7 +34,7 @@ namespace Example { // ... add any other service you need ... // this call adds the basic services for sending of webhooks - services.AddWebhookNotifier(webhooks => { + services.AddWebhookNotifier(webhooks => { // This registers a subscription resolver that is backed // by the a Mongo database (from the Deveel.Webhooks.Mongo package) webhooks.UseMongoSubscriptionResolver(); @@ -62,12 +42,8 @@ namespace Example { // for this implementation we use a Mongo database as // persistent layer of the subscriptions wekhooks.UseMongoDb(mongo => { - mongo.SetConnectionString(Configuration - .GetConnectionString("MongoWebhooks")) - .SetDatabase("example_app") - .SetSubscriptionsCollection("webhook_subs") - // Optional: enables the storage the webhook delivery results - .SetWebhooksCollection("webhooks_results"); + mongo.UseConnectionString(Configuration + .GetConnectionString("MongoWebhooks")); }); // Optional: add a filter engine that handles string-based "linq" filters @@ -112,7 +88,7 @@ namespace Example { [HttpPost("{tenantId}")] public async Task Post([FromRoute]string tenantId, [FromBody] EventModel webEvent) { - // The service requires an instance of EventInfo + // The service requires an instance of 'EventInfo' // to trigger the notification process and we assume // your EventModel class can create one var eventInfo = webEvent.AsEventInfo(); @@ -139,7 +115,9 @@ namespace Example { In order to resolve the subscriptions to a given event, the `IWebhookSubscriptionResolver` service is used: this service is responsible for the retrieval of the subscriptions that match the event type, in scope of a tenant. -The framework provides a default implementation of this service, that is backed by the MongoDb database, included in the `Deveel.Webhooks.Mongo` package, but other implementations will be provided in the future. +Some of the libraries implementing a persistent layer for the subscriptions, provide an implementation of the `IWebhookSubscriptionResolver` service, that can be used to resolve the subscriptions from the persistent layer. + +Future implementations of the contract might provide a way to resolve the subscriptions from a cache, or from a remote service. ## Logging Results diff --git a/docs/advanced_usage_data_layers.md b/docs/notifications/webhook_subscription_data_layers.md similarity index 98% rename from docs/advanced_usage_data_layers.md rename to docs/notifications/webhook_subscription_data_layers.md index eaf5839..ee7fb58 100644 --- a/docs/advanced_usage_data_layers.md +++ b/docs/notifications/webhook_subscription_data_layers.md @@ -1,4 +1,4 @@ -# Webhook Management Data Layers +# Webhook Subscription Management Data Layers _**Note**: This part of the framework will sonn go through a major refactoring and the documentation as to be consider provisional_ diff --git a/docs/advanced_usage_ef.md b/docs/notifications/webhook_subscription_ef.md similarity index 100% rename from docs/advanced_usage_ef.md rename to docs/notifications/webhook_subscription_ef.md diff --git a/docs/advanced_usage_filters.md b/docs/notifications/webhook_subscription_filters.md similarity index 83% rename from docs/advanced_usage_filters.md rename to docs/notifications/webhook_subscription_filters.md index 6170e51..5a3074b 100644 --- a/docs/advanced_usage_filters.md +++ b/docs/notifications/webhook_subscription_filters.md @@ -1,19 +1,3 @@ - - # Filtering Webhook Subscriptions To allow a webhook to be triggered only when a specific event occurs, subscriptions can define some filtering conditions that are evaluated before the webhook is delivered. diff --git a/docs/basic_usage_management.md b/docs/notifications/webhook_subscription_management.md similarity index 100% rename from docs/basic_usage_management.md rename to docs/notifications/webhook_subscription_management.md diff --git a/docs/advanced_usage_mongodb.md b/docs/notifications/webhook_subscription_mongodb.md similarity index 100% rename from docs/advanced_usage_mongodb.md rename to docs/notifications/webhook_subscription_mongodb.md diff --git a/docs/receivers/README.md b/docs/receivers/README.md new file mode 100644 index 0000000..e3f251c --- /dev/null +++ b/docs/receivers/README.md @@ -0,0 +1,9 @@ +# Receivers + +The framework provides a set of libraries that can be used to receive webhooks from external sources. + +| Receiver | Description | +| ------------------------------------ | -------------------------------------------------- | +| **[Facebook](facebook_receiver.md)** | Receive webhooks from Facebook Messenger | +| **[SendGrid](sendgrid_receiver.md)** | Receive webhooks and emails from SendGrid | +| **[Twilio](twilio_receiver.md)** | Receive webhooks and SMS/WhatsApp messages from Twilio | \ No newline at end of file diff --git a/docs/advanced_usage_custom_receiver.md b/docs/receivers/custom_receiver.md similarity index 100% rename from docs/advanced_usage_custom_receiver.md rename to docs/receivers/custom_receiver.md diff --git a/docs/facebook_receiver.md b/docs/receivers/facebook_receiver.md similarity index 100% rename from docs/facebook_receiver.md rename to docs/receivers/facebook_receiver.md diff --git a/docs/basic_usage_receive.md b/docs/receivers/receive_webhooks.md similarity index 100% rename from docs/basic_usage_receive.md rename to docs/receivers/receive_webhooks.md diff --git a/docs/sendgrid_receiver.md b/docs/receivers/sendgrid_receiver.md similarity index 100% rename from docs/sendgrid_receiver.md rename to docs/receivers/sendgrid_receiver.md diff --git a/docs/twilio_receiver.md b/docs/receivers/twilio_receiver.md similarity index 100% rename from docs/twilio_receiver.md rename to docs/receivers/twilio_receiver.md diff --git a/docs/basic_usage_send.md b/docs/send_webhooks.md similarity index 100% rename from docs/basic_usage_send.md rename to docs/send_webhooks.md diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 5ce138d..8d9c238 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -3,7 +3,7 @@ net6.0 enable enable - 2.1.0 + 2.1.1 Deveel false true