https://github.com/deveel/ratatosk
Attempts to define a standard pattern for the implementation of messaging across multiple channels and providers
https://github.com/deveel/ratatosk
connector connectors dotnet dotnet-core email message messaging pattern push schema sendgrid sms telegram twilio validation whatsapp
Last synced: 18 days ago
JSON representation
Attempts to define a standard pattern for the implementation of messaging across multiple channels and providers
- Host: GitHub
- URL: https://github.com/deveel/ratatosk
- Owner: deveel
- License: mit
- Created: 2025-07-24T20:53:30.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-06-08T06:21:04.000Z (19 days ago)
- Last Synced: 2026-06-08T08:06:50.122Z (19 days ago)
- Topics: connector, connectors, dotnet, dotnet-core, email, message, messaging, pattern, push, schema, sendgrid, sms, telegram, twilio, validation, whatsapp
- Language: C#
- Homepage:
- Size: 3.61 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 36
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
[](https://www.nuget.org/packages/Ratatosk.Abstractions/)
[](https://codecov.io/gh/deveel/ratatosk)
[](LICENSE)
[](https://dotnet.microsoft.com/)
[](https://ratatosk.deveel.org)
# Ratatosk
> **Note**
> The project was originally named **Deveel Messaging**: on the day _25.05.2026_ it has been rebranded as **Ratatosk**, after the mythological squirrel that runs up and down Yggdrasil, the World Tree, carrying messages between the eagle at the top and the dragon at the roots — a fitting symbol for a messaging framework.
Ratatosk is a .NET framework that gives you one consistent way to work with SMS, email, push notifications, and chat channels.
Instead of coding directly against each provider SDK, you build an `IMessage`, send it through an `IChannelConnector`, and handle a predictable `OperationResult`. That keeps your app code stable even if providers change.
The repository currently targets `.NET 8`, `.NET 9`, and `.NET 10`.
Current stable release: **v1.0.1** (pre-release packages available from `main` builds).
## Features
- **Unified message model** — `IMessage` with fluent `MessageBuilder`, typed endpoints, and 12 content types (text, HTML, media, binary, JSON, location, template, multipart, button, quick reply, carousel, list picker)
- **Schema-driven validation** — every connector declares capabilities, parameters, and constraints via `IChannelSchema`; catch invalid messages before they reach the provider
- **Pluggable authentication** — API key, token, basic auth, OAuth 2.0, Firebase service account, or custom providers
- **DI-first design** — `AddMessaging()` + `AddConnector()` integration with `Microsoft.Extensions.DependencyInjection`
- **Standardized results** — all operations return `OperationResult` with success/failure semantics
- **Schema derivation** — derive restricted schemas from a master for feature tiers or environment-specific constraints
- **IMessagingClient facade** — disposable high-level client with lazy initialization and named channel routing
- **Extensible** — implement `ChannelConnectorBase` to add any provider; built-in logging scopes, state management, and error wrapping
- **5 ready-made connectors** — Twilio (SMS/WhatsApp), SendGrid (email), Firebase (push), Facebook Messenger, Telegram Bot
- **Sender identity management** — registry-backed senders with resolution, caching, and per-channel selector strategies
## What this project does not do
- Queueing and scheduling
- Durable storage for audit/history
- Workflow orchestration
Those are application-level concerns, so you can choose your own architecture.
## Packages
| Package | Description | NuGet |
|---|---|---|
| `Ratatosk.Abstractions` | Message model with fluent builder, typed endpoints, 12 content types (including interactive), properties, and batch support. Zero external dependencies. | [](https://www.nuget.org/packages/Ratatosk.Abstractions/) |
| `Ratatosk` | DI registration (`AddMessaging`), `IMessagingClient` facade (disposable), connector factory, service collection extensions. | [](https://www.nuget.org/packages/Ratatosk/) |
| `Ratatosk.Connector.Abstractions` | Connector contracts, schemas, authentication, validation, result types. Reference for custom connector libraries. | [](https://www.nuget.org/packages/Ratatosk.Connector.Abstractions/) |
| `Ratatosk.Connectors` | Abstract connector base (`ChannelConnectorBase`) with state management and error wrapping, `ChannelSchema` builder, schema registry, auth manager, connector builder API. | [](https://www.nuget.org/packages/Ratatosk.Connectors/) |
| `Ratatosk.Twilio` | Twilio SMS, MMS, WhatsApp messaging with status callbacks and template support. | [](https://www.nuget.org/packages/Ratatosk.Twilio/) |
| `Ratatosk.Sendgrid` | SendGrid transactional and bulk email with HTML, multipart, templates, attachments, and event webhook processing. | [](https://www.nuget.org/packages/Ratatosk.Sendgrid/) |
| `Ratatosk.Firebase` | Firebase Cloud Messaging push for device tokens and topics, with batch sends and dry-run mode. | [](https://www.nuget.org/packages/Ratatosk.Firebase/) |
| `Ratatosk.Facebook` | Facebook Messenger Page-based messaging with text, media, quick replies, and webhook inbound. | [](https://www.nuget.org/packages/Ratatosk.Facebook/) |
| `Ratatosk.Telegram` | Telegram bot messaging with rich text, media, locations, and webhook-based updates. | [](https://www.nuget.org/packages/Ratatosk.Telegram/) |
| `Ratatosk.Senders` | Sender identity infrastructure: `ISenderRepository`, `ISenderResolver`, cache, per-connector configuration, `MessageBuilder.FromSender()` extension. | [](https://www.nuget.org/packages/Ratatosk.Senders/) |
| `Ratatosk.Senders.InMemory` | In-memory `IRepository` for development and testing. | [](https://www.nuget.org/packages/Ratatosk.Senders.InMemory/) |
| `Ratatosk.Senders.EntityFramework` | EF Core persistence for the sender identity registry (`SenderDbContext`, `EntitySenderRepository`, `DbSender`). | [](https://www.nuget.org/packages/Ratatosk.Senders.EntityFramework/) |
| `Ratatosk.Extensions.OpenTelemetry` | Convenience extensions for wiring Ratatosk telemetry sources into OpenTelemetry SDK. | [](https://www.nuget.org/packages/Ratatosk.Extensions.OpenTelemetry/) |
## Quick example
```csharp
// Register in DI (Startup / Program)
services.AddMessaging()
.AddTwilioSmsConnector(options => {
options.AccountSid = "...";
options.AuthToken = "...";
});
// Resolve and send
public class NotificationService(IMessagingClient messaging)
{
public async Task SendAsync(CancellationToken ct)
{
var message = new MessageBuilder()
.WithId("order-confirm-123")
.FromPhone("+15550001111")
.ToPhone("+15550002222")
.WithText("Your order has been confirmed!")
.Build();
var result = await messaging.SendMessageAsync(message, ct);
if (!result.IsSuccess())
{
throw new InvalidOperationException(
result.Error?.Message ?? "Failed to send message");
}
}
}
```
## Documentation
If you want to go deeper, the documentation provides practical, step-by-step guidance for designing channels, wiring connectors, validating messages, and operating the framework in real projects.
Start from the docs home and follow the path that best matches what you are building: [docs/README.md](docs/README.md).
### Suggested reading paths
- **First integration** - Start with the framework concepts, then wire a minimal implementation, and finally pick a connector guide for your channel.
([Framework overview](docs/framework-overview.md) -> [Quickstart](docs/quickstart.md) -> [Connector index](docs/connectors/README.md))
- **Custom connector authoring** - Learn schema design first, then implement connector behaviour, then register and resolve channels at runtime.
([Channel schema](docs/channel-schema.md) -> [Connector implementation](docs/connector-implementation.md) -> [Installation](docs/installation.md))
- **Validation-first integration** - Model endpoints, apply validation rules, and extend validation when channel-specific constraints grow.
([Message model](docs/messaging-model.md) -> [Message validation](docs/message-validation.md) -> [Channel schema](docs/channel-schema.md))
- **Sender identity management** - Set up sender registries, define lifecycle rules, and understand runtime resolution and caching.
([Sender management](docs/senders/sender-management.md) -> [Sender resolution](docs/senders/sender-resolution.md) -> [Sender Manager sample](docs/samples/sender-manager.md))
## Roadmap
The project roadmap is tracked in detail in [ROADMAP.md](ROADMAP.md). The summary below highlights the upcoming milestones and the main features planned for each release.
### v0.4.0 — Framework Foundations ✓
Strengthens quality gates, release automation, observability, and docs completeness across the existing connector ecosystem.
- [x] **Test coverage target (≥ 80%)** — Enforce minimum line coverage per library in CI.
- [x] **CI/CD pipeline hardening** — Automate build, test, compatibility checks, signing, and NuGet publishing from release tags.
- [x] **Structured logging improvements** — Standardize event IDs, scopes, and `LoggerMessage` patterns across connectors.
- [x] **Documentation completeness** — Complete XML API docs and connector guides with consistent coverage.
### v0.5.0 — Inbound Messaging ✓
Completes the receive-side model for current connectors to support bidirectional messaging scenarios.
- [x] **Twilio inbound messages (SMS/WhatsApp)** — Parse inbound payloads into framework messages and endpoints.
- [x] **SendGrid inbound parse support** — Map multipart inbound emails, content, and attachments into the message model.
- [x] **Firebase inbound messages** — Support upstream device data messages through the same receive abstractions.
### v1.0.0 — First Stable Release ✓
Locks the public API and ships stable package releases with production-ready guarantees.
- [x] **API freeze and compatibility enforcement** — Prevent breaking API changes without a major version bump.
- [x] **NuGet GA release** — Publish stable `Ratatosk.*` packages without prerelease suffixes.
- [x] **Interactive content model** — Add cross-channel abstractions for buttons, quick replies, carousels, and lists.
- [x] **Sender identity model** — Provide typed sender identities for phone, email, and bot-based channels.
### v1.1.0 — Resilience & Observability
Adds retry/circuit-breaker policies, OpenTelemetry signals, health checks, and timeout controls.
- [x] **Retry policies** — Polly-based retry and circuit-breaker integrated at the connector base level.
- [x] **OpenTelemetry tracing & metrics** — ActivitySources, Meters, and histograms per connector.
- [ ] **Health checks** — ASP.NET Core `IHealthCheck` implementations auto-registered per connector.
- [ ] **Connector-level timeout configuration** — Per-operation timeout via the DI registration API.
### v1.2.0 — New SaaS Connectors
Extends the connector ecosystem with additional major cloud messaging providers.
- [ ] **Slack** — Incoming Webhooks and Bot API support with Block Kit content mapping.
- [ ] **Microsoft Teams** — Incoming Webhooks and Bot Framework API with Adaptive Card support.
- [ ] **WhatsApp Business API** — Direct Meta Cloud API connector (text, media, interactive, templates).
- [ ] **Viber Business** — Viber Business Messages API (text, image, rich media, keyboards).
- [ ] **LINE** — LINE Messaging API (text, image, video, audio, Flex Messages).
### v1.3.0 — Protocol Connectors
Raw protocol support for teams with direct carrier or Apple developer relationships.
- [ ] **Protocol connector base classes** — Session management, connection lifecycle, reconnection policies.
- [ ] **SMPP** — Direct SMSC connectivity (v3.4 session client, `submit_sm`/`deliver_sm` mapping).
- [ ] **SMTP** — Direct email delivery via MailKit (RFC 5321 MIME messages).
- [ ] **RCS** — Rich Communication Services Business Messaging API.
- [ ] **APNs (direct)** — Apple Push Notification HTTP/2 API without Firebase dependency.
### v1.4.0 — Content Adaptation & Transcoding
Transcoding layer that converts content between types for multi-channel delivery.
- [ ] **`IContentTranscoder` abstraction** — Generic content conversion with resolution registry.
- [ ] **Built-in transcoders** — HTML-to-plaintext, HTML-to-Markdown, Markdown-to-GSM-7, and more.
- [ ] **Channel-aware content fallback** — Automatic fallback to best available content type per channel.
- [ ] **SMS segmentation** — GSM-7/UCS-2 segment counting and encoding analysis.
- [ ] **Character encoding detection** — `SmsEncodingAnalyzer` for pre-send encoding warnings.
### v1.5.0 — Address & Number Validation
Validation layer for recipient addresses across all channels.
- [ ] **E.164 normalization** — libphonenumber-based canonical phone number formatting.
- [ ] **HLR lookup** — Optional Home Location Register reachability checks before SMS send.
- [ ] **Number portability awareness** — Ported number routing in the SMPP connector.
- [ ] **Email address validation** — RFC 5321 syntax, MX record, and disposable domain checks.
- [ ] **`IAddressValidator` abstraction** — Extensible validation chain per connector.
### v1.6.0 — Tooling & Instrumentation
Developer and operator tooling for the framework.
- [ ] **`dotnet new` connector scaffold** — Template package for bootstrapping new connectors.
- [ ] **ASP.NET Core diagnostic middleware** — Runtime connector state, health, and counters endpoint.
### v2.0.0 — Conversations
Conversation management as a first-class framework concept.
- [ ] **`IConversation` abstraction** — Thread of messages with participants, status, and history.
- [ ] **Conversation state model** — State transitions, persistence, in-memory store for testing.
- [ ] **Conversation correlation** — Link inbound replies to originating conversations.
- [ ] **Multi-channel conversations** — Span single conversations across SMS, WhatsApp, email, and more.
- [ ] **Multi-tenant channel registry** — Tenant-aware connector and schema resolution.
- [ ] **xUnit test helpers** — Fake inbound injectors and assertion helpers for conversation flows.
### v2.1.0 — Message Templates
Provider-agnostic template model with local and server-side rendering.
- [ ] **`IMessageTemplate` abstraction** — Named templates with locale, content structure, and variable schema.
- [ ] **Variable substitution engine** — Local rendering with placeholder resolution and type-safe binding.
- [ ] **Per-connector template rendering** — Bridge between framework templates and provider-native systems.
- [ ] **Template registry** — Central store with startup validation and locale-aware resolution.
For milestone-level detail, rationale, and dependencies, see [ROADMAP.md](ROADMAP.md).
## Versioning and Releases
The project uses a simple GitHub Flow-based release model:
- `main` is the only long-lived branch
- merges to `main` produce preview packages with an `-alpha.N` suffix
- stable packages are produced only from `vX.Y.Z` tags on commits already in `main`
Package versions are calculated automatically with GitVersion, so versions should not be edited manually in project files.
## Contributing
Contributions are welcome and appreciated.
If you want to contribute:
- Open an issue to discuss bugs, features, or design changes
- Check the existing documentation and package boundaries before proposing API changes
- Submit focused pull requests with tests when behavior changes
The contribution workflow follows GitHub Flow: create a short-lived branch from `main`, open a pull request, and let CI produce preview packages from `main` after merge.
For local setup, coding conventions, and the contribution workflow, read [CONTRIBUTING.md](CONTRIBUTING.md).
## License
This project is released under the MIT License.
You can use it in personal, academic, and commercial projects, including closed-source applications, provided that the license notice is preserved.
See [LICENSE](LICENSE) for the full text and terms.
## Contributors
[](https://github.com/deveel/ratatosk/graphs/contributors)