Merge pull request #3 from PavelAgarkov/pre-release

rebuild architecture of package

Author: PavelAgarkov

README.md

@@ -1,24 +1,26 @@
 # rate-envelope-queue
 
-Лёгкий пакет для управления пулом задач (**envelopes**) поверх `k8s.io/client-go/util/workqueue` с ограничением параллелизма, ретраями, периодическим планированием, **stamps (middleware)** и хуками до/после выполнения.
+Лёгкий пакет для управления пулом задач (**envelopes**) поверх `k8s.io/client-go/util/workqueue` с ограничением
+параллелизма, ретраями, периодическим планированием, **stamps (middleware)** и хуками до/после выполнения.
 
-> Основано на `workqueue` из client-go: очередь дедуплицирует одинаковые элементы (один и тот же **указатель**) и поддерживает rate-limiting / отложенное перепланирование.
+> Основано на `workqueue` из client-go: очередь дедуплицирует одинаковые элементы (один и тот же **указатель**) и
+> поддерживает rate-limiting / отложенное перепланирование.
 
 ---
 
 ## Что нового в API
 
 - **Builder-подход для Envelope** — поля неэкспортируемые, настройка через `NewEnvelope(opts...)` и `With*`-опции:
   ```go
-  e := pkg.NewEnvelope(
-      pkg.WithId(1),
-      pkg.WithType("email"),
-      pkg.WithInterval(5*time.Second),
-      pkg.WithDeadline(3*time.Second),
-      pkg.WithBeforeHook(func(ctx context.Context, e *pkg.Envelope) error { return nil }),
-      pkg.WithInvoke(func(ctx context.Context) error { return nil }),
-      pkg.WithAfterHook(func(ctx context.Context, e *pkg.Envelope) error { return nil }),
-      pkg.WithStampsPerEnvelope(/* per-envelope stamps */),
+  e := NewEnvelope(
+      WithId(1),
+      WithType("email"),
+      WithInterval(5*time.Second),
+      WithDeadline(3*time.Second),
+      WithBeforeHook(func(ctx context.Context, e *Envelope) error { return nil }),
+      WithInvoke(func(ctx context.Context) error { return nil }),
+      WithAfterHook(func(ctx context.Context, e *Envelope) error { return nil }),
+      WithStampsPerEnvelope(/* per-envelope stamps */),
   )
   ```
   Для чтения используйте геттеры: `GetId()`, `GetType()`, `GetStamps()`.
@@ -28,7 +30,8 @@
     - Per-envelope — через `WithStampsPerEnvelope(...)` в `NewEnvelope(...)`.
     - Порядок исполнения: **сначала глобальные, затем per-envelope** (глобальные — внешние).
 
-- **Тайм‑бюджеты для хуков** в `BeforeAfterStamp`: по умолчанию рекомендуем `frac=0.5` и `min=800ms` → `max(50% от deadline, 800ms)`.
+- **Тайм‑бюджеты для хуков** в `BeforeAfterStamp`: по умолчанию рекомендуем `frac=0.5` и `min=800ms` →
+  `max(50% от deadline, 800ms)`.
 
 ---
 
@@ -39,10 +42,12 @@
 - **Дедлайны**: `deadline > 0` ограничивает время выполнения `invoke` (оборачивается таймаутом в воркере).
 - **Хуки**: `beforeHook` / `afterHook` с отдельным тайм-бюджетом (через `BeforeAfterStamp(WithHookTimeout)`).
 - **Stamps (middleware)**: глобальные и per-envelope; компонуются в цепочку (**chain**).
-- **Остановка типа**: `ErrStopEnvelope` из любого места (`beforeHook`/`invoke`/`afterHook`) кладёт `_type` в **blacklist**.
+- **Остановка типа**: `ErrStopEnvelope` из любого места (`beforeHook`/`invoke`/`afterHook`) кладёт `_type` в **blacklist
+  **.
 - **Backoff/ретраи**: дефолтный лимитер = `MaxOf(Exponential(1s..30s), TokenBucket(5 rps, burst=10))`.
 - **Грациозная остановка**: режимы `Drain`/`Stop`.
-- **Безопасность при паниках**: паника внутри обработки **конверта** → `Forget+Done` и лог стека; паника воркера также перехватывается.
+- **Безопасность при паниках**: паника внутри обработки **конверта** → `Forget+Done` и лог стека; паника воркера также
+  перехватывается.
 
 ---
 
@@ -58,11 +63,11 @@
 ## Установка
 
 ```bash
-go get github.com/PavelAgarkov/rate-pool/pkg
+go get github.com/PavelAgarkov/rate-envelope-queue
 ```
 
 ```go
-import "github.com/PavelAgarkov/rate-pool/pkg"
+import "github.com/PavelAgarkov/rate-envelope-queue"
 ```
 
 ---
@@ -73,47 +78,47 @@ import "github.com/PavelAgarkov/rate-pool/pkg"
 ctx, cancel := context.WithCancel(context.Background())
 defer cancel()
 
-q := pkg.NewRateEnvelopeQueue(
-    pkg.WithLimitOption(3),           // 3 воркера
-    pkg.WithWaitingOption(true),      // ждать завершения горутин при Stop()
-    pkg.WithStopModeOption(pkg.Drain),
-    pkg.WithStamps(                   // глобальные stamps (внешние)
-        pkg.BeforeAfterStamp(pkg.WithHookTimeout), // 50% от deadline, минимум 800ms
-        pkg.LoggingStamp(log.Default()),
-    ),
+q := NewRateEnvelopeQueue(
+WithLimitOption(3), // 3 воркера
+WithWaitingOption(true), // ждать завершения горутин при Stop()
+WithStopModeOption(Drain),
+WithStamps(                   // глобальные stamps (внешние)
+BeforeAfterStamp(WithHookTimeout), // 50% от deadline, минимум 800ms
+LoggingStamp(log.Default()),
+),
 )
 
-email := pkg.NewEnvelope(
-    pkg.WithId(1),
-    pkg.WithType("email"),
-    pkg.WithInterval(5*time.Second),
-    pkg.WithDeadline(3*time.Second),
-    pkg.WithBeforeHook(func(ctx context.Context, e *pkg.Envelope) error {
-        fmt.Println("before:", e.GetId(), time.Now())
-        return nil
-    }),
-    pkg.WithInvoke(func(ctx context.Context) error {
-        // имитируем работу; уважайте ctx.Done()
-        time.Sleep(5 * time.Second)
-        fmt.Println("invoke email", time.Now())
-        return nil
-    }),
-    pkg.WithAfterHook(func(ctx context.Context, e *pkg.Envelope) error {
-        fmt.Println("after:", e.GetId(), time.Now())
-        // Остановим дальнейшие email
-        return pkg.ErrStopEnvelope
-    }),
+email := NewEnvelope(
+WithId(1),
+WithType("email"),
+WithInterval(5*time.Second),
+WithDeadline(3*time.Second),
+WithBeforeHook(func (ctx context.Context, e *Envelope) error {
+fmt.Println("before:", e.GetId(), time.Now())
+return nil
+}),
+WithInvoke(func (ctx context.Context) error {
+// имитируем работу; уважайте ctx.Done()
+time.Sleep(5 * time.Second)
+fmt.Println("invoke email", time.Now())
+return nil
+}),
+WithAfterHook(func (ctx context.Context, e *Envelope) error {
+fmt.Println("after:", e.GetId(), time.Now())
+// Остановим дальнейшие email
+return ErrStopEnvelope
+}),
 )
 
-metrics := pkg.NewEnvelope(
-    pkg.WithId(2),
-    pkg.WithType("metrics"),
-    pkg.WithInterval(3*time.Second),
-    pkg.WithDeadline(1*time.Second),
-    pkg.WithInvoke(func(ctx context.Context) error {
-        fmt.Println("metrics tick", time.Now())
-        return nil
-    }),
+metrics := NewEnvelope(
+WithId(2),
+WithType("metrics"),
+WithInterval(3*time.Second),
+WithDeadline(1*time.Second),
+WithInvoke(func (ctx context.Context) error {
+fmt.Println("metrics tick", time.Now())
+return nil
+}),
 )
 
 q.Start(ctx)
@@ -129,17 +134,18 @@ q.Stop()
 
 ## Поведение очереди
 
-| Сценарий                                                         | Действие очереди                                                                 |
-|------------------------------------------------------------------|----------------------------------------------------------------------------------|
-| `invoke` вернул `nil`                                            | `Forget`; если `interval > 0` → `AddAfter(interval)`                             |
-| Контекст задачи истёк/отменён (`DeadlineExceeded`/`Canceled`)    | `Forget`; если периодическая → `AddAfter(interval)`                              |
-| `ErrStopEnvelope` (из `beforeHook`/`invoke`/`afterHook`)         | `Forget` + поместить `_type` в **blacklist**                                     |
-| Ошибка в `beforeHook` (не `ErrStopEnvelope`)                     | Периодические: `AddRateLimited`; одноразовые: `Forget`                           |
-| Ошибка в `invoke` (не `ErrStopEnvelope`)                         | Периодические: `AddRateLimited`; одноразовые: `Forget`                           |
-| Ошибка в `afterHook` (не `ErrStopEnvelope`)                      | Возвращается наверх → те же правила, что и для обычной ошибки                   |
-| Паника внутри обработки элемента                                 | Элемент `Forget+Done`, стек логируется; воркер продолжает работу                 |
+| Сценарий                                                      | Действие очереди                                                 |
+|---------------------------------------------------------------|------------------------------------------------------------------|
+| `invoke` вернул `nil`                                         | `Forget`; если `interval > 0` → `AddAfter(interval)`             |
+| Контекст задачи истёк/отменён (`DeadlineExceeded`/`Canceled`) | `Forget`; если периодическая → `AddAfter(interval)`              |
+| `ErrStopEnvelope` (из `beforeHook`/`invoke`/`afterHook`)      | `Forget` + поместить `_type` в **blacklist**                     |
+| Ошибка в `beforeHook` (не `ErrStopEnvelope`)                  | Периодические: `AddRateLimited`; одноразовые: `Forget`           |
+| Ошибка в `invoke` (не `ErrStopEnvelope`)                      | Периодические: `AddRateLimited`; одноразовые: `Forget`           |
+| Ошибка в `afterHook` (не `ErrStopEnvelope`)                   | Возвращается наверх → те же правила, что и для обычной ошибки    |
+| Паника внутри обработки элемента                              | Элемент `Forget+Done`, стек логируется; воркер продолжает работу |
 
-> Валидация: для периодических задач `deadline` **не должен превышать** `interval` — иначе `ErrAdditionEnvelopeToQueueBadIntervals`.
+> Валидация: для периодических задач `deadline` **не должен превышать** `interval` — иначе
+`ErrAdditionEnvelopeToQueueBadIntervals`.
 
 ---
 
@@ -150,11 +156,13 @@ Stamps — это обёртки вокруг `Invoker` (обработчика
 - **Глобальные stamps** — задаются на очередь через `WithStamps(...)`.
 - **Per-envelope stamps** — через `WithStampsPerEnvelope(...)` в `NewEnvelope(...)`.
 
-Порядок: глобальные идут **первее** и становятся **внешними** (самыми «оборачивающими»), затем per-envelope — **внутренние**.
+Порядок: глобальные идут **первее** и становятся **внешними** (самыми «оборачивающими»), затем per-envelope — *
+*внутренние**.
 
 ### Встроенные stamps
 
-- `BeforeAfterStamp(withTimeout)` — исполняет `beforeHook` и `afterHook` с отдельными тайм-бюджетами; любые ошибки, кроме `ErrStopEnvelope`, **возвращаются** наверх. Рекомендуемая функция тайм-бюджета:  
+- `BeforeAfterStamp(withTimeout)` — исполняет `beforeHook` и `afterHook` с отдельными тайм-бюджетами; любые ошибки,
+  кроме `ErrStopEnvelope`, **возвращаются** наверх. Рекомендуемая функция тайм-бюджета:  
   `WithHookTimeout(ctx, base=deadline, frac=0.5, min=800ms)` → `max(50% от deadline, 800ms)`.
 - `LoggingStamp(l *log.Logger)` — логирует длительность и ошибку обработки конверта.
 
@@ -165,55 +173,58 @@ Stamps — это обёртки вокруг `Invoker` (обработчика
 ### Конструктор и геттеры
 
 ```go
-e := pkg.NewEnvelope(opts...)
+e := NewEnvelope(opts...)
 
-id   := e.GetId()
+id := e.GetId()
 name := e.GetType()
-st   := e.GetStamps()
+st := e.GetStamps()
 ```
 
 ### Опции `Envelope`
 
 ```go
-pkg.WithId(id uint64)
-pkg.WithType(t string)
-pkg.WithInterval(d time.Duration)      // 0 = одноразовая задача
-pkg.WithDeadline(d time.Duration)      // 0 = без таймаута
-pkg.WithBeforeHook(func(ctx context.Context, e *Envelope) error)
-pkg.WithInvoke(func(ctx context.Context) error)
-pkg.WithAfterHook(func(ctx context.Context, e *Envelope) error)
-pkg.WithStampsPerEnvelope(stamps ...Stamp)
+WithId(id uint64)
+WithType(t string)
+WithInterval(d time.Duration) // 0 = одноразовая задача
+WithDeadline(d time.Duration) // 0 = без таймаута
+WithBeforeHook(func(ctx context.Context, e *Envelope) error)
+WithInvoke(func (ctx context.Context) error)
+WithAfterHook(func (ctx context.Context, e *Envelope) error)
+WithStampsPerEnvelope(stamps ...Stamp)
 ```
 
 ### Опции очереди
 
 ```go
-pkg.WithLimitOption(n)                        // число воркеров (>0)
-pkg.WithWaitingOption(true|false)             // ждать ли завершения воркеров в Stop()
-pkg.WithStopModeOption(pkg.Drain|pkg.Stop)
-pkg.WithLimiterOption(customLimiter)          // если не задан — дефолтный
-pkg.WithWorkqueueConfigOption(conf)           // конфиг workqueue
-pkg.WithStamps(stamps...)                     // глобальные stamps
+WithLimitOption(n) // число воркеров (>0)
+WithWaitingOption(true|false)             // ждать ли завершения воркеров в Stop()
+WithStopModeOption(Drain|Stop)
+WithLimiterOption(customLimiter) // если не задан — дефолтный
+WithWorkqueueConfigOption(conf)  // конфиг workqueue
+WithStamps(stamps...) // глобальные stamps
 ```
 
 ### Ошибки
 
 ```go
-pkg.ErrStopEnvelope                         // поместить `_type` в blacklist
-pkg.ErrEnvelopeInBlacklist                  // попытка добавить тип из blacklist
-pkg.ErrEnvelopeQueueIsNotRunning            // Add до Start/после Stop
-pkg.ErrAdditionEnvelopeToQueueBadFields     // пустой тип / nil invoke / отрицательные интервалы
-pkg.ErrAdditionEnvelopeToQueueBadIntervals  // deadline > interval для периодических
+ErrStopEnvelope                        // поместить `_type` в blacklist
+ErrEnvelopeInBlacklist                 // попытка добавить тип из blacklist
+ErrEnvelopeQueueIsNotRunning           // Add до Start/после Stop
+ErrAdditionEnvelopeToQueueBadFields    // пустой тип / nil invoke / отрицательные интервалы
+ErrAdditionEnvelopeToQueueBadIntervals // deadline > interval для периодических
 ```
 
 ---
 
 ## Эксплуатационные заметки
 
-- **Один объект — один запуск**: текущая реализация рассчитана на одноразовый жизненный цикл `Start/Stop`. Для повторного использования создайте **новый объект** очереди.
-- **Дедупликация**: для указателей — по адресу. Не «переиспользуйте» один и тот же указатель для разных логических задач.
+- **Один объект — один запуск**: текущая реализация рассчитана на одноразовый жизненный цикл `Start/Stop`. Для
+  повторного использования создайте **новый объект** очереди.
+- **Дедупликация**: для указателей — по адресу. Не «переиспользуйте» один и тот же указатель для разных логических
+  задач.
 - **Jitter**: чтобы периодические задачи не «стреляли строем», можно добавить случайный сдвиг к `AddAfter`.
-- **Соблюдайте контекст** в `invoke`/хуках: долгие операции должны уважать `ctx.Done()`; иначе получится «карусель» таймаутов с перепланированием.
+- **Соблюдайте контекст** в `invoke`/хуках: долгие операции должны уважать `ctx.Done()`; иначе получится «карусель»
+  таймаутов с перепланированием.
 
 ---