{"id":29029656,"url":"https://github.com/shellvon/go-sender","last_synced_at":"2025-06-26T08:36:11.601Z","repository":{"id":300387426,"uuid":"1005924972","full_name":"shellvon/go-sender","owner":"shellvon","description":"A flexible Go library for sending notifications via Webhook, WeCom, Email, Telegram, and more.","archived":false,"fork":false,"pushed_at":"2025-06-21T11:15:15.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T12:24:54.552Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shellvon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T05:16:47.000Z","updated_at":"2025-06-21T11:15:18.000Z","dependencies_parsed_at":"2025-06-21T12:24:58.584Z","dependency_job_id":"f60cfd3a-23b7-4902-bf20-e9c35b7bec8a","html_url":"https://github.com/shellvon/go-sender","commit_stats":null,"previous_names":["shellvon/go-sender"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shellvon/go-sender","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellvon%2Fgo-sender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellvon%2Fgo-sender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellvon%2Fgo-sender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellvon%2Fgo-sender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shellvon","download_url":"https://codeload.github.com/shellvon/go-sender/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shellvon%2Fgo-sender/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262030818,"owners_count":23247726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-26T08:36:04.231Z","updated_at":"2025-06-26T08:36:11.593Z","avatar_url":"https://github.com/shellvon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go-Sender\n\n\u003e ⚠️ **Project Status: In Active Development**\n\u003e\n\u003e This project is under heavy development. APIs may be unstable and subject to change. Please use with caution in production environments.\n\nEnglish | [中文](./README_CN.md)\n\nA high-performance, extensible Go message sending framework supporting multiple notification channels and rich middleware capabilities.\n\n---\n\n## Design Philosophy\n\nGo-Sender is designed around the **Decorator Pattern** and **Plugin Architecture**, making it easy to add new notification channels or cross-cutting concerns without changing your business logic.\n\n### Core Design Principles\n\n- **🔄 Decoupling**: Business code only cares about sending messages, not how they're delivered\n- **🔌 Pluggable**: Easy to add new providers or middleware through interfaces\n- **🛡️ Reliability**: Built-in retry, circuit breaker, and rate limiting\n- **📊 Observable**: Comprehensive metrics and health checks\n- **🧩 Flexible**: Support for multiple instances, strategies, and configurations\n\n### Architecture Overview\n\n```\nBusiness Logic → Sender → ProviderDecorator → Provider\n                      ↓\n                Middleware Chain:\n                - Rate Limiter\n                - Circuit Breaker\n                - Retry Policy\n                - Queue\n                - Metrics\n```\n\n## ✨ Features\n\n### 🚦 Supported Providers (Grouped by Type)\n\n### 📱 SMS \u0026 Voice\n\n| Provider                  | Website                                        | API Docs                                                                                                                             | Provider Doc                            |\n| ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |\n| Aliyun (阿里云)           | [aliyun.com](https://www.aliyun.com)           | [API](https://help.aliyun.com/zh/sms/developer-reference/api-dysmsapi-2017-05-25-sendsms)                                            | [SMS README](./providers/sms/README.md) |\n| Tencent Cloud (腾讯云)    | [cloud.tencent.com](https://cloud.tencent.com) | [SMS API](https://cloud.tencent.com/document/product/382/55981) / [Voice API](https://cloud.tencent.com/document/product/1128/51559) | [SMS README](./providers/sms/README.md) |\n| Huawei Cloud (华为云)     | [huaweicloud.com](https://www.huaweicloud.com) | [API](https://support.huaweicloud.com/intl/zh-cn/api-msgsms/sms_05_0001.html)                                                        | [SMS README](./providers/sms/README.md) |\n| Volcano Engine (火山引擎) | [volcengine.com](https://www.volcengine.com)   | [API](https://www.volcengine.com/docs/63933)                                                                                         | [SMS README](./providers/sms/README.md) |\n| Yunpian (云片)            | [yunpian.com](https://www.yunpian.com)         | [API](https://www.yunpian.com/official/document/sms/zh_CN/domestic_list)                                                             | [SMS README](./providers/sms/README.md) |\n| CL253 (创蓝 253)          | [253.com](https://www.253.com)                 | [API](https://www.253.com/api)                                                                                                       | [SMS README](./providers/sms/README.md) |\n| Submail (赛邮)            | [mysubmail.com](https://www.mysubmail.com/)    | [API](https://www.mysubmail.com/documents)                                                                                           | [SMS README](./providers/sms/README.md) |\n| UCP (云之讯)              | [ucpaas.com](https://www.ucpaas.com)           | [API](http://docs.ucpaas.com)                                                                                                        | [SMS README](./providers/sms/README.md) |\n| Juhe (聚合数据)           | [juhe.cn](https://www.juhe.cn)                 | [API](https://www.juhe.cn/docs)                                                                                                      | [SMS README](./providers/sms/README.md) |\n| SMSBao (短信宝)           | [smsbao.com](https://www.smsbao.com)           | [API](https://www.smsbao.com/openapi)                                                                                                | [SMS README](./providers/sms/README.md) |\n| Yuntongxun (云讯通)       | [yuntongxun.com](https://www.yuntongxun.com)   | [API](https://www.yuntongxun.com/developer-center)                                                                                   | [SMS README](./providers/sms/README.md) |\n\n### 📧 Email\n\n| Provider           | Website                                        | API Docs                                                              | Provider Doc                                |\n| ------------------ | ---------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------- |\n| go-mail (SMTP)     | [go-mail](https://github.com/wneessen/go-mail) | [Docs](https://pkg.go.dev/github.com/wneessen/go-mail)                | [Email README](./providers/email/README.md) |\n| (Planned) Mailgun  | [mailgun.com](https://www.mailgun.com/)        | [API](https://documentation.mailgun.com/en/latest/api_reference.html) | N/A                                         |\n| (Planned) Mailjet  | [mailjet.com](https://www.mailjet.com/)        | [API](https://dev.mailjet.com/email/guides/send-api-v31/)             | N/A                                         |\n| (Planned) Mailtrap | [mailtrap.io](https://mailtrap.io/)            | [API](https://api-docs.mailtrap.io/docs)                              | N/A                                         |\n| (Planned) Brevo    | [brevo.com](https://www.brevo.com/)            | [API](https://developers.brevo.com/docs)                              | N/A                                         |\n| (Planned) Braze    | [braze.com](https://www.braze.com/)            | [API](https://www.braze.com/docs/api/)                                | N/A                                         |\n\n### 🤖 IM/Bot/Enterprise Notification\n\n- [WeCom Bot (企业微信机器人)](https://developer.work.weixin.qq.com/document/path/91770) ([Provider Doc](./providers/wecombot/README.md))\n- [DingTalk Bot (钉钉机器人)](https://open.dingtalk.com/document/robots/custom-robot-access) ([Provider Doc](./providers/dingtalk/README.md))\n- [Lark/Feishu (飞书/国际版)](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN) ([Provider Doc](./providers/lark/README.md))\n- [Telegram](https://core.telegram.org/bots/api) ([Provider Doc](./providers/telegram/README.md))\n- (Planned) Slack ([API](https://api.slack.com/messaging/webhooks))\n- [ServerChan](https://sct.ftqq.com/) ([Provider Doc](./providers/serverchan/README.md))\n\n### 🌐 Universal Push / Webhook\n\nAll the following are supported via the [Webhook Provider](./providers/webhook/README.md) (generic HTTP integration):\n\n- [ntfy](https://ntfy.sh/)\n- [IFTTT](https://ifttt.com/)\n- [Bark](https://github.com/Finb/Bark)\n- [PushDeer](https://github.com/easychen/pushdeer)\n- [PushPlus](https://pushplus.hxtrip.com/)\n- [PushAll](https://pushall.ru/)\n- [PushBack](https://pushback.io/)\n- [Pushy](https://pushy.me/)\n- [Pushbullet](https://www.pushbullet.com/)\n- [Gotify](https://gotify.net/)\n- [OneBot](https://github.com/botuniverse/onebot)\n- [Push](https://push.techulus.com/)\n- [Pushjet](https://pushjet.io/)\n- [Pushsafer](https://www.pushsafer.com/)\n- [Pushover](https://pushover.net/)\n- [Simplepush](https://simplepush.io/)\n- [Zulip](https://zulip.com/)\n- [Mattermost](https://mattermost.com/)\n- [Discord](https://discord.com/) (message push supported via webhook; for advanced/interaction features, a dedicated provider is needed)\n\n\u003e See [Webhook Provider documentation](./providers/webhook/README.md) for details and examples of supported push platforms.\n\n### 🚀 Push Providers\n\n| Provider                                 | Website                                                                     | API Docs                                                           | Provider Doc |\n| ---------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------ |\n| (Planned) FCM (Firebase Cloud Messaging) | [firebase.google.com](https://firebase.google.com/products/cloud-messaging) | [API](https://firebase.google.com/docs/cloud-messaging)            | N/A          |\n| (Planned) JPush (极光推送)               | [jiguang.cn](https://www.jiguang.cn/)                                       | [API](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_push/) | N/A          |\n\n---\n\n### 🛡️ Advanced Reliability\n\n- Built-in retry, circuit breaker, and rate limiting\n- Token bucket and sliding window algorithms\n- Health checks and observability\n\n### 🎛️ Multi-Instance \u0026 Strategy Support\n\n- Multiple accounts/providers per channel\n- Load balancing: round-robin, random, weighted, health-based\n- Context-aware strategy override\n\n### 🧩 Middleware \u0026 Plugin Architecture\n\n- Rate limiter, circuit breaker, retry, queue, metrics, etc.\n\n### 📊 Observability\n\n- Metrics, tracing, health checks\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\ngo get github.com/shellvon/go-sender\n```\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n\n    gosender \"github.com/shellvon/go-sender\"\n    \"github.com/shellvon/go-sender/core\"\n    \"github.com/shellvon/go-sender/providers/email\"\n)\n\nfunc main() {\n    // Create sender instance\n    sender := gosender.NewSender(nil)\n\n    // Configure email provider\n    emailConfig := email.Config{\n        BaseConfig: core.BaseConfig{\n            Strategy: core.StrategyRoundRobin,\n        },\n        Accounts: []email.Account{\n            {\n                Name:     \"primary\",\n                Host:     \"smtp.gmail.com\",\n                Port:     587,\n                Username: \"your-email@gmail.com\",\n                Password: \"your-password\",\n                From:     \"your-email@gmail.com\",\n                Weight:   1,\n            },\n        },\n    }\n\n    emailProvider, err := email.New(emailConfig)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Register provider\n    sender.RegisterProvider(core.ProviderTypeEmail, emailProvider, nil)\n\n    // Send message\n    ctx := context.Background()\n    emailMsg := \u0026email.Message{\n        To:      []string{\"recipient@example.com\"},\n        Subject: \"Hello from Go-Sender\",\n        Body:    \"This is a test message\",\n    }\n\n    err = sender.Send(ctx, emailMsg)\n    if err != nil {\n        log.Printf(\"Failed to send message: %v\", err)\n    }\n\n    defer sender.Close()\n}\n```\n\n## 🔧 Advanced Features\n\n### 1. Custom Retry Policies\n\n```go\n// Set global retry policy\nretryPolicy := core.NewRetryPolicy(\n    core.WithRetryMaxAttempts(5),\n    core.WithRetryInitialDelay(time.Second),\n    core.WithRetryBackoffFactor(2.0),\n)\nsender.SetRetryPolicy(retryPolicy)\n\n// Or use per-message retry policy (overrides global)\nerr := sender.Send(ctx, message, core.WithSendRetryPolicy(retryPolicy))\n```\n\n### 2. Multi-Instance with Load Balancing\n\n```go\n// WeCom Bot with multiple instances\nwecomConfig := wecombot.Config{\n    BaseConfig: core.BaseConfig{\n        Strategy: core.StrategyWeighted,\n    },\n    Accounts: []core.Account{\n        {\n            Name:     \"bot1\",\n            Key:      \"YOUR_KEY_1\",\n            Weight:   100,\n            Disabled: false,\n        },\n        {\n            Name:     \"bot2\",\n            Key:      \"YOUR_KEY_2\",\n            Weight:   80,\n            Disabled: false,\n        },\n    },\n}\n```\n\n### 3. Queue and Async Sending\n\n```go\n// Set memory queue\nqueue := queue.NewMemoryQueue[*core.QueueItem](1000)\nsender.SetQueue(queue)\n\n// Send message asynchronously\nerr := sender.Send(ctx, message, core.WithSendAsync())\n```\n\n### 4. Circuit Breaker and Rate Limiting\n\n```go\n// Circuit breaker\ncircuitBreaker := circuitbreaker.NewMemoryCircuitBreaker(\n    \"email-provider\",\n    5,                    // maxFailures\n    30*time.Second,       // resetTimeout\n)\nsender.SetCircuitBreaker(circuitBreaker)\n\n// Rate limiter\nrateLimiter := ratelimiter.NewTokenBucketRateLimiter(10, 20) // 10 QPS, burst 20\nsender.SetRateLimiter(rateLimiter)\n```\n\n### 5. Health Monitoring\n\n```go\n// Check system health\nhealth := sender.HealthCheck(ctx)\nif health.Status != core.HealthStatusHealthy {\n    log.Printf(\"System unhealthy: %+v\", health)\n\n    // Check specific provider\n    if providerHealth, exists := health.Providers[core.ProviderTypeEmail]; exists {\n        log.Printf(\"Email provider status: %s\", providerHealth.Status)\n    }\n}\n```\n\n## 🎯 Extending Go-Sender\n\n### Adding New Providers\n\n```go\ntype MyProvider struct{}\n\nfunc (p *MyProvider) Send(ctx context.Context, msg core.Message) error {\n    // Your implementation\n    return nil\n}\n\nfunc (p *MyProvider) Name() string {\n    return \"my-provider\"\n}\n\n// Register your provider\nsender.RegisterProvider(\"my-provider\", \u0026MyProvider{}, nil)\n```\n\n## 📊 Supported Strategies\n\n| Strategy       | Description                | Use Case               |\n| -------------- | -------------------------- | ---------------------- |\n| `round_robin`  | Distribute requests evenly | Load balancing         |\n| `random`       | Random selection           | Simple distribution    |\n| `weighted`     | Weight-based selection     | Priority-based routing |\n| `health_based` | Health-based selection     | Custom health checks   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellvon%2Fgo-sender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshellvon%2Fgo-sender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellvon%2Fgo-sender/lists"}