Skip to content

Commit 0fb4328

Browse files
GerfeyGerfey
committed
update: readme
1 parent 762c480 commit 0fb4328

File tree

2 files changed

+188
-68
lines changed

2 files changed

+188
-68
lines changed

‎README.md

Lines changed: 62 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Messenger Documentation
1+
# Messenger
22

33
[![CI](https://github.com/Gerfey/messenger/actions/workflows/ci.yml/badge.svg)](https://github.com/Gerfey/messenger/actions/workflows/ci.yml)
44
[![Security](https://github.com/Gerfey/messenger/actions/workflows/security.yml/badge.svg)](https://github.com/Gerfey/messenger/actions/workflows/security.yml)
@@ -7,124 +7,118 @@
77
[![Go Reference](https://pkg.go.dev/badge/github.com/Gerfey/messenger.svg)](https://pkg.go.dev/github.com/Gerfey/messenger)
88
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
99

10-
> Pre-release MVP version. Requires Go 1.24+
10+
> ⚠️ `v0.6.0` is a pre-release version — feel free to test and report issues!
1111
12-
## Installation
12+
> 📚 Full documentation available in the [GitHub Wiki](https://github.com/Gerfey/messenger/wiki/Documentation)
1313
14-
```bash
15-
go get github.com/gerfey/[email protected]
16-
```
14+
🇷🇺 [Русская версия](README.ru.md)
1715

18-
## Overview
19-
- **Multiple Transports**: AMQP (RabbitMQ), In-Memory
16+
## ✨ Features
17+
- **Multiple Transports**: AMQP (RabbitMQ), In-Memory (sync)
2018
- **Middleware Chain**: Extensible middleware system for message processing
2119
- **Event-Driven**: Built-in event dispatcher for lifecycle hooks
2220
- **Retry Mechanism**: Configurable retry strategies with exponential backoff
2321
- **Message Routing**: Flexible routing system for message distribution
2422
- **Stamps System**: Metadata attachment for message tracking
25-
- **YAML Configuration**: Easy configuration management
23+
- **YAML Configuration**: Easy configuration management with `%env(...)%` support
24+
25+
## 📦 Installation
26+
> Requires Go 1.24+
27+
```bash
28+
go get github.com/gerfey/[email protected]
29+
```
2630

27-
## Quick Start
31+
## 🚀 Quick Start
2832

29-
### 1. Define Your Message
33+
### Define Your Message
3034

3135
```go
36+
package main
37+
3238
type HelloMessage struct {
3339
Text string
3440
}
3541
```
3642

37-
### 2. Create a Handler
43+
### Create a Handler
3844

3945
```go
46+
package main
47+
4048
type HelloHandler struct{}
4149

4250
func (h *HelloHandler) Handle(ctx context.Context, msg *HelloMessage) error {
43-
fmt.Printf("Received: %s\n", msg.Text)
51+
fmt.Println("Hello:", msg.Text)
4452
return nil
4553
}
4654
```
4755

48-
### 3. Configure and Run
56+
### Create config file `messenger.yaml`:
4957

5058
```yaml
51-
# messenger.yaml
5259
default_bus: default
5360

5461
buses:
5562
default: ~
5663

5764
transports:
58-
amqp:
59-
dsn: "amqp://guest:guest@localhost:5672/"
60-
options:
61-
auto_setup: true
62-
exchange:
63-
name: messages
64-
type: topic
65+
sync:
66+
dsn: "in-memory://"
6567

6668
routing:
67-
package.HelloMessage: amqp
69+
main.HelloMessage: sync
6870
```
71+
> 💡 If no transport is configured for a message, it will be executed synchronously by default (inline handler execution).
6972
70-
```go
71-
package main
73+
### Initialize messenger:
7274
73-
import (
74-
"context"
75-
"log/slog"
76-
77-
"github.com/Gerfey/messenger/builder"
78-
"github.com/Gerfey/messenger/config"
79-
)
80-
81-
func main() {
82-
ctx := context.Background()
83-
logger := slog.Default()
84-
85-
// Load configuration
86-
cfg, err := config.LoadConfig("messenger.yaml")
87-
if err != nil {
88-
logger.Error("failed to load config", "error", err)
89-
return
90-
}
91-
92-
// Build messenger
93-
b := builder.NewBuilder(cfg, logger)
94-
b.RegisterHandler(&HelloHandler{})
95-
96-
messenger, err := b.Build()
97-
if err != nil {
98-
logger.Error("failed to build messenger", "error", err)
99-
return
100-
}
101-
102-
// Start consuming
103-
go func() {
104-
if err := messenger.Run(ctx); err != nil {
105-
logger.Error("messenger failed", "error", err)
106-
}
107-
}()
108-
109-
// Send message
110-
bus, _ := messenger.GetDefaultBus()
111-
bus.Dispatch(ctx, &HelloMessage{Text: "Hello, World!"})
75+
```go
76+
cfg, errConfig := config.LoadConfig("messenger.yaml")
77+
if errConfig != nil {
78+
l.Error("ERROR load config", "error", errConfig)
79+
return
11280
}
81+
82+
b := builder.NewBuilder(cfg, slog.Default())
83+
b.RegisterHandler(&HelloHandler{})
84+
m, _ := b.Build()
85+
86+
ctx := context.Background()
87+
go m.Run(ctx)
88+
89+
bus, _ := m.GetDefaultBus()
90+
_, _ = bus.Dispatch(ctx, &HelloMessage{Text: "World"})
91+
92+
time.Sleep(5 * time.Second)
11393
```
11494

115-
## Contributing
95+
## 🔍 More Examples
96+
97+
* ✅ Commands with void return
98+
* ✅ Queries with return value access
99+
* ✅ Retry and Dead Letter Queue
100+
* ✅ Custom Middleware and Transports
101+
* ✅ Event Listeners and Lifecycle Hooks
102+
103+
> See [Usage Scenarios](https://github.com/Gerfey/messenger/wiki/Usage-Scenarios) for commands, queries, return values and advanced use-cases.
104+
105+
## 🤝 Contributing
116106

117107
1. Fork the repository
118108
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
119109
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
120110
4. Push to the branch (`git push origin feature/amazing-feature`)
121111
5. Open a Pull Request
122112

123-
## License
113+
## ⚖️ License
124114

125115
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
126116

127-
## Acknowledgments
117+
## ⭐️ Support
118+
119+
If you find this project useful, please consider starring ⭐️ it and sharing with others!
120+
121+
## 🙏 Acknowledgments
128122

129123
- Inspired by [Symfony Messenger](https://symfony.com/doc/current/messenger.html)
130-
- Built with ❤️ for the Go community
124+
- Built with ❤️ for the Go community

‎README.ru.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Messenger
2+
3+
[![CI](https://github.com/Gerfey/messenger/actions/workflows/ci.yml/badge.svg)](https://github.com/Gerfey/messenger/actions/workflows/ci.yml)
4+
[![Security](https://github.com/Gerfey/messenger/actions/workflows/security.yml/badge.svg)](https://github.com/Gerfey/messenger/actions/workflows/security.yml)
5+
[![codecov](https://codecov.io/gh/Gerfey/messenger/branch/main/graph/badge.svg)](https://codecov.io/gh/Gerfey/messenger)
6+
[![Go Report Card](https://goreportcard.com/badge/github.com/Gerfey/messenger)](https://goreportcard.com/report/github.com/Gerfey/messenger)
7+
[![Go Reference](https://pkg.go.dev/badge/github.com/Gerfey/messenger.svg)](https://pkg.go.dev/github.com/Gerfey/messenger)
8+
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9+
10+
> ⚠️ Версия `v0.6.0` — это пре-релиз. Тестируйте и сообщайте о багах!
11+
12+
> 📚 Полная документация доступна на [GitHub Wiki](https://github.com/Gerfey/messenger/wiki/Documentation)
13+
14+
🇬🇧 [English README](README.md)
15+
16+
---
17+
18+
## ✨ Возможности
19+
- **Множественные транспорты**: AMQP (RabbitMQ), In-Memory (`sync`)
20+
- **Цепочка middleware**: Расширяемая система промежуточной обработки
21+
- **Событийный движок**: Встроенный dispatcher событий жизненного цикла
22+
- **Механизм повторов**: Настраиваемые стратегии ретраев с поддержкой DLQ
23+
- **Маршрутизация сообщений**: Гибкое сопоставление сообщений и транспортов
24+
- **Система метаданных (Stamps)**: Для трассировки и поведения сообщений
25+
- **YAML-конфигурация**: С поддержкой переменных окружения `%env(...)%`
26+
27+
## 📦 Установка
28+
> Требуется Go версии **1.24+**
29+
```bash
30+
go get github.com/gerfey/[email protected]
31+
```
32+
33+
## 🚀 Быстрый старт
34+
35+
### Определите сообщение
36+
37+
```go
38+
package main
39+
40+
type HelloMessage struct {
41+
Text string
42+
}
43+
```
44+
45+
### Создайте обработчик
46+
47+
```go
48+
package main
49+
50+
type HelloHandler struct{}
51+
52+
func (h *HelloHandler) Handle(ctx context.Context, msg *HelloMessage) error {
53+
fmt.Println("Hello:", msg.Text)
54+
return nil
55+
}
56+
```
57+
58+
### Создайте конфигурационный файл `messenger.yaml`:
59+
60+
```yaml
61+
default_bus: default
62+
63+
buses:
64+
default: ~
65+
66+
transports:
67+
sync:
68+
dsn: "in-memory://"
69+
70+
routing:
71+
main.HelloMessage: sync
72+
```
73+
> 💡 Если транспорт для сообщения не указан — оно будет выполнено синхронно (inline).
74+
75+
### Инициализация и запуск:
76+
77+
```go
78+
cfg, errConfig := config.LoadConfig("messenger.yaml")
79+
if errConfig != nil {
80+
l.Error("ERROR load config", "error", errConfig)
81+
return
82+
}
83+
84+
b := builder.NewBuilder(cfg, slog.Default())
85+
b.RegisterHandler(&HelloHandler{})
86+
m, _ := b.Build()
87+
88+
ctx := context.Background()
89+
go m.Run(ctx)
90+
91+
bus, _ := m.GetDefaultBus()
92+
_, _ = bus.Dispatch(ctx, &HelloMessage{Text: "World"})
93+
94+
time.Sleep(5 * time.Second)
95+
```
96+
97+
## 🔍 Больше примеров
98+
99+
* ✅ Команды без возврата значения
100+
* ✅ Запросы с возвратом результата
101+
* ✅ Повторные попытки и Dead Letter Queue
102+
* ✅ Пользовательские middleware и транспорты
103+
* ✅ Слушатели событий и хуки жизненного цикла
104+
105+
> Смотри [Сценарии использования](https://github.com/Gerfey/messenger/wiki/Сценарии-использования).
106+
107+
## 🤝 Как внести вклад
108+
109+
1. Форкните репозиторий
110+
2. Создайте новую ветку (`git checkout -b feature/amazing-feature`)
111+
3. Сделайте коммит (`git commit -m 'Add some amazing feature'`)
112+
4. Запушьте изменения (`git push origin feature/amazing-feature`)
113+
5. Откройте Pull Request
114+
115+
## ⚖️ Лицензия
116+
117+
Проект лицензирован под [MIT](LICENSE).
118+
119+
## ⭐️ Поддержка
120+
121+
Если вам полезен этот проект — поставьте ⭐️ и расскажите другим!
122+
123+
## 🙏 Благодарности
124+
125+
- Вдохновлено [Symfony Messenger](https://symfony.com/doc/current/messenger.html)
126+
- Сделано с ❤️ для сообщества Go

0 commit comments

Comments
 (0)