v1.5.0 - Documentation Site

Overview

Complete documentation transformation from markdown files to a Hugo-based GitHub Pages site with professional presentation.

Documentation Site: https://vnykmshr.github.io/goflow/

Highlights

Documentation Site

• Hugo static site with hugo-book theme
• Hierarchical navigation: Guides → Features → Reference
• Dark/light mode support for code blocks and mermaid diagrams
• Custom logo with Go blue gradient
• GitHub Actions deployment to GitHub Pages

Content Organization

• Why goflow - Hero narrative explaining problem space and architecture
• Guides - Getting Started, Decision Guide, Migration
• Features - Rate Limiting, Task Scheduling, Streaming
• Reference - Contributing, Security, Changelog

Test Coverage Improvements

• workerpool: 77.6% → 92.9% coverage
• stream: 77.2% → 80.9% coverage

Installation

go get github.com/vnykmshr/goflow@v1.5.0

Breaking Changes

None. This release focuses on documentation improvements.

Full Changelog

v1.4.0...v1.5.0

v1.4.0 - Performance & Polish

Summary

Performance optimizations and code quality improvements. Non-breaking changes only.

Changes

Added

• Comprehensive benchmark suite (make benchmark)
  • Stream benchmarks (FromSlice, Filter, Map, ToSlice, Reduce, Distinct)
  • Channel benchmarks (Send/Receive, contention, backpressure strategies)
  • WorkerPool benchmarks (submit/execute cycle, throughput, scaling)
• Performance baseline documentation

Changed

• Pipeline stats use atomic operations for counters, reducing lock contention
• Cleaned up label formatting in benchmark helpers

Benchmark Baseline

Operation	ns/op	B/op	allocs/op
Stream/FromSlice-1k	92	112	2
Stream/Filter-1k	278,398	15,904	25
Channel/Send-100	1,078	303	5
Pipeline/Concurrent	1,042	440	6
WorkerPool/Submit-4w	1,557	247	2

Installation

go get github.com/vnykmshr/goflow@v1.4.0

Full Changelog: v1.3.0...v1.4.0

v1.3.0 - Critical Bug Fixes

What's Changed

Bug Fixes

• Fix goroutine leaks in stream package when streams aren't fully consumed (#9)
• Fix silent error dropping in stream operations - now uses fail-fast behavior (#9)
• Add SubmitWithContext for proper context propagation in worker pool (#9)

Performance Improvements

• O(1) waiter removal in concurrency limiter using swap-and-pop (was O(n))
• Efficient context watching - replaced goroutine-per-call with context.AfterFunc in channel package

Breaking Changes

• Package rename: errors → gferrors to avoid conflict with Go stdlib

Testing

• Added goleak.VerifyTestMain to workerpool, channel, and stream packages
• Comprehensive tests for SubmitWithContext scenarios

Migration Guide

errors → gferrors

// Before
import "github.com/vnykmshr/goflow/pkg/common/errors"
errors.NewValidationError(...)

// After  
import "github.com/vnykmshr/goflow/pkg/common/gferrors"
gferrors.NewValidationError(...)

New: SubmitWithContext

// Now available for context propagation
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

pool.SubmitWithContext(ctx, task)  // Context propagates to task execution

Full Changelog

v1.2.0...v1.3.0

v1.2.0 - Test Suite Overhaul & Critical Fixes

v1.2.0 - Test Suite Overhaul & Critical Fixes

🎯 Highlights

This release focuses on test quality, reliability, and stability with comprehensive test suite improvements, critical bug fixes, and removal of untested code.

Key Improvements

• ✅ 100% Test Coverage for critical utility packages (errors, validation)
• ✅ 10 New Integration Tests verifying cross-package workflows
• ✅ 2 Critical Bug Fixes (channel timeout deadlock, data races)
• ✅ Zero Flaky Tests with new async testing helpers
• ✅ ~1,800 LOC Removed (untested distributed rate limiting)

🧪 Test Suite Overhaul

Test Infrastructure

New Shared Test Utilities (internal/testutil)

• MockClock: Thread-safe time mocking with controllable time advancement
• MockWriter: Configurable writer mock for async/error testing
• Consolidated 3 duplicate implementations, saving ~170 lines

Async Testing Helpers

// Wait for condition with timeout
Eventually(t, func() bool { return counter.Load() == 10 }, timeout, interval)

// Wait for specific atomic values
WaitForInt32(t, &counter, expectedValue, timeout)

// Track callback invocations
tracker := NewCallbackTracker()
tracker.Mark()
tracker.AssertCalled(t)

Test Coverage Improvements

Package	Before	After	Lines Added
pkg/common/errors	0%	100%	332
pkg/common/validation	0%	100%	307
internal/testutil	0%	44.3%	260

Total: +900 lines of high-quality tests

Integration Testing

New Integration Test Framework (test/integration/)

• 10 comprehensive tests covering real-world workflows
• No mocks - tests actual component interactions
• Examples:
  • Pipeline + Rate Limiting
  • Pipeline + Worker Pool
  • Streaming (Channel + Writer + Stream)
  • Channel Backpressure Strategies
  • Concurrent Access Patterns
  • Context Cancellation

🐛 Critical Bug Fixes

1. Channel Context Timeout Deadlock

Problem: blockingSend() and blockingReceive() in pkg/streaming/channel would hang indefinitely when context timed out, causing CI tests to timeout after 600 seconds.

Root Cause: sync.Cond.Wait() doesn't respect context cancellation.

Solution:

• Added goroutine to monitor context cancellation and wake up waiters
• Added context check after waking from Wait()
• Tests now complete in <100ms instead of timing out

Impact: High - affects any code using channels with timeouts

2. Data Race in Test Utilities

Problem: Race detector found unsynchronized boolean variable access in TestAssertEventually and TestEventuallyWithContext.

Solution: Replaced plain bool with atomic.Int32 for thread-safe access.

Impact: Medium - only affected test infrastructure, not library code

3. Flaky Integration Test

Problem: TestPipelineWithWorkerPool had race condition checking stats before all goroutines completed.

Solution: Used sync.WaitGroup to ensure completion before assertions.

⚡ Breaking Changes

Removed Distributed Rate Limiting

Removed: pkg/ratelimit/distributed package (~1,800 LOC, 0% test coverage)

Rationale:

• Zero test coverage on complex Redis operations and Lua scripts
• External Redis dependency
• High maintenance burden
• Better alternatives exist

Migration Path:
Use specialized libraries designed for distributed rate limiting:

• github.com/go-redis/redis_rate - Redis-based
• github.com/sethvargo/go-limiter - Multi-backend

Impact: Users of distributed rate limiting must migrate to alternatives. Local rate limiters (token bucket, leaky bucket, concurrency) are unaffected.

📈 Code Quality Improvements

Eliminated Flaky Tests

Before: Tests used time.Sleep() and fixed delays

time.Sleep(200 * time.Millisecond)
if count := atomic.LoadInt32(&executed); count != 2 {
    t.Errorf("expected 2, got %d", count)
}

After: Tests use condition-based waiting

WaitForInt32(t, &executed, 2, 500*time.Millisecond)
// Fails fast with clear error message

Benefits:

• ✅ Tests pass faster (exit early when condition met)
• ✅ Tests fail faster (timeout only when truly stuck)
• ✅ More reliable in CI/CD environments
• ✅ Better error messages

Code Deduplication

• Removed ~183 lines of duplicate test code
• Consolidated 3 MockClock implementations
• Consolidated MockWriter implementation
• Replaced custom contains() with strings.Contains()

📊 Statistics

Overall Changes

• 33 files changed
• 2,262 insertions (new tests, documentation)
• 2,640 deletions (distributed package, duplicates)
• Net: -378 lines (better code-to-functionality ratio)

Test Suite Health

• 0 packages with 0% coverage (was 3)
• 2 packages with 100% coverage (was 0)
• 10 integration tests (was 0)
• 0 flaky tests (was 3+)

CI/CD Results

All tests pass reliably:

• ✅ Lint: 14s
• ✅ Test (Go 1.21.x): 39s
• ✅ Test (Go 1.23.x): 35s
• ✅ Build: 18s

📚 Documentation

New Documentation

• TEST_IMPROVEMENTS.md: Complete test suite review with metrics
• test/integration/README.md: Integration testing best practices

Updated Documentation

• README.md: Removed distributed rate limiting mentions
• DECISION_GUIDE.md: Updated rate limiting options
• SECURITY.md: Removed Redis-specific security section
• CHANGELOG.md: Comprehensive v1.2.0 changelog

🔧 Minor Improvements

• Fixed Example_peek flaky output ordering
• Updated CI workflow to remove distributed example build step
• Improved pre-commit hook (removed obsolete --fast flag)
• Corrected workerpool.Shutdown() usage in GETTING_STARTED.md

⚙️ Compatibility

• Go: 1.21+ (tested with 1.21.x and 1.23.x)
• Breaking Changes: Removed pkg/ratelimit/distributed package
• Deprecations: leakybucket.New() and leakybucket.NewWithConfig() (use Safe variants)
• Dependencies: Removed github.com/redis/go-redis/v9

📦 Migration Guide

If Using Distributed Rate Limiting

Option 1: Use go-redis/redis_rate

import "github.com/go-redis/redis_rate/v10"

limiter := redis_rate.NewLimiter(redisClient)
res, err := limiter.Allow(ctx, "key", redis_rate.PerSecond(10))

Option 2: Use sethvargo/go-limiter

import "github.com/sethvargo/go-limiter"

store, _ := memorystore.New(&memorystore.Config{Tokens: 10, Interval: time.Second})
limiter, _ := httplimiter.NewMiddleware(store, httplimiter.IPKeyFunc())

If Using Local Rate Limiters

No changes required! Token bucket, leaky bucket, and concurrency limiters continue to work as before.

🙏 Acknowledgments

This release represents a significant investment in test quality and reliability. The comprehensive test suite overhaul ensures the library is production-ready and maintainable long-term.

---

Full Changelog: v1.1.0...v1.2.0

v1.1.0 - Safe Constructors & Documentation Improvements

What's New

New Features 🎉

Safe Constructors for Worker Pool

• Added NewSafe() and NewWithConfigSafe() methods that return errors instead of panicking
• Original New() and NewWithConfig() methods are now deprecated but remain for backward compatibility
• Provides production-ready error handling for invalid configurations

// Recommended: Safe constructor with error handling
pool, err := workerpool.NewSafe(5, 100)
if err != nil {
    log.Fatal(err)
}

// Or with custom config
pool, err := workerpool.NewWithConfigSafe(workerpool.Config{
    WorkerCount: 5,
    QueueSize:   100,
    TaskTimeout: 30 * time.Second,
})
if err != nil {
    log.Fatal(err)
}

Documentation Improvements 📚

Streamlined Documentation (60% reduction)

• Reduced verbose AI-generated documentation across all packages
• Removed unnecessary emoji usage for professional presentation
• Improved error handling examples (replaced panic(err) with log.Fatal(err))
• Updated all examples to use new Safe constructors
• Updated README with best practices

Enhanced Security Documentation

• Added comprehensive Redis security configuration guidelines
• Improved distributed rate limiting security recommendations

Infrastructure & Developer Experience 🛠️

golangci-lint v2 Migration

• Upgraded to golangci-lint v2.5.0 for improved linting
• Migrated configuration to v2 schema
• Local and CI environments now use identical linting configuration
• Added appropriate deprecation warnings suppression in test files

CI/CD Improvements

• Upgraded to golangci-lint-action v7
• Made Codecov upload non-blocking to prevent CI failures
• Faster and more reliable builds

Code Quality 🧹

Removed Unused Code

• Removed unused metrics package infrastructure
• Cleaned up deprecated metric collection code
• Reduced maintenance burden and improved clarity

Migration Guide

For Existing Users

The new Safe constructors are backward compatible. Your existing code will continue to work with deprecation warnings:

// Old (still works, but deprecated)
pool := workerpool.New(5, 100)

// New (recommended)
pool, err := workerpool.NewSafe(5, 100)
if err != nil {
    log.Fatal(err)
}

We recommend migrating to Safe constructors for better error handling in production.

Full Changelog

Features

• feat: add Safe constructors for workerpool (6b16df3)

Documentation

• docs: reduce verbose documentation by 60% (d23ec99)
• docs: update all examples to use Safe constructors (284134e)
• docs: remove emojis and improve error handling examples (97bc0e1)
• docs: update README to use Safe constructors (05f52cb)

Fixes & Improvements

• fix: upgrade golangci-lint-action to v7 for v2 support (c82c503)
• fix: migrate golangci-lint config to v2 schema (7fa8013)
• ci: upgrade golangci-lint to v2.5.0 and suppress deprecation warnings (484c6af)
• ci: make codecov upload non-blocking (590cd92)
• refactor: remove unused metrics package and add Redis security docs (88a3a40)

Infrastructure

• chore: project hygiene improvements and infrastructure hardening (cd8f4bb)
• fix: remove version field from golangci config for compatibility (403c236)
• fix: update golangci-lint to latest version for config v2 support (df24860)

Compatibility

• Go: 1.21+ (tested with 1.21.x and 1.23.x)
• Breaking Changes: None - fully backward compatible
• Deprecations: workerpool.New() and workerpool.NewWithConfig() (use Safe variants)

---

Full Diff: v1.0.3...v1.1.0

v1.0.3 - Repository Cleanup & Code Quality

🧹 Repository Cleanup & Code Quality Improvements

This release focuses on code maintainability, consistency, and developer experience improvements based on a comprehensive periodic repository review.

✨ Added

• Common validation helpers (pkg/common/validation) - Reusable validation functions to reduce boilerplate and ensure consistent error messages across all rate limiters
• Migration guide (docs/MIGRATION.md) - Comprehensive guide for deprecated APIs and removed packages
• golangci-lint version specification - Added version: 2 to .golangci.yml for modern linter compatibility

⚠️ Deprecated

• leakybucket.New() and leakybucket.NewWithConfig() - These panic on invalid input. Use NewSafe() variants instead (will be removed in v2.0.0)

🗑️ Removed

• pkg/common/context package - Removed unnecessary abstraction layer over standard library context package. Use standard library directly.
• golangci-lint --fast flag - Removed obsolete flag from pre-commit hook

🐛 Fixed

• Documentation: Corrected workerpool.Shutdown() usage example in GETTING_STARTED.md
• Examples: Fixed linter issues (errcheck, unused parameters) in all example files
• Tests: Resolved nil pointer dereference warnings in pipeline tests

🔄 Changed

• Rate limiters now use shared validation helpers for consistent error messages
• All validation logic consolidated for better maintainability
• Examples updated with proper error handling patterns

📚 Documentation

• README updated with link to migration guide
• All deprecation notices include clear migration paths
• CHANGELOG updated with unreleased changes

---

Migration Required? Only if you were using the pkg/common/context package (unlikely). See Migration Guide for details.

Full Changelog: v1.0.2...v1.0.3

goflow v1.0.2

Changes

Changelog

All notable changes to goflow will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[v1.0.2] - 2025-01-17

Fixed

• CI/CD Issues: Resolved compilation failures in examples and test files
• Build Reliability: Fixed all deprecated API usage across the codebase
• Code Quality: Resolved formatting and linting issues causing CI failures

Changed

• CI Workflow: Split into separate lint, test, and build jobs for better parallelization
• Linting Configuration: More practical rules with appropriate exclusions for tests and examples
• Error Handling: Enhanced error propagation in all Safe API functions

Improved

Installation

go get github.com/vnykmshr/goflow@v1.0.2

What's Changed

See the CHANGELOG.md for detailed changes.
Full Changelog: v1.0.1...v1.0.2

goflow v1.0.1 - Production Safety Release

🚀 goflow v1.0.1 - Production Safety Release

🎯 Overview

This is a production safety-focused patch release that removes deprecated panic-prone functions and enhances error handling across the goflow library.

🔧 Major Changes

✅ Removed Deprecated Functions (BREAKING)

• Removed bucket.New() and bucket.NewWithConfig() - use bucket.NewSafe() instead
• Removed concurrency.New() and concurrency.NewWithConfig() - use concurrency.NewSafe() instead
• These functions could panic on invalid configuration, which is not suitable for production

🛡️ Production Safety Improvements

• All internal components now use safe constructors with proper error handling
• Eliminated panic paths in rate limiter creation
• Enhanced error propagation in metrics integration
• Updated benchmark tests to use safe constructors

📚 Documentation & Governance

• Added comprehensive CONTRIBUTING.md with development guidelines
• Added CHANGELOG.md following Keep a Changelog format
• Complete contribution workflow and testing instructions

🔄 Migration Guide

Before (v1.0.0):

limiter := bucket.New(100, 200) // Could panic!

After (v1.0.1):

limiter, err := bucket.NewSafe(100, 200)
if err != nil {
    return fmt.Errorf("failed to create limiter: %w", err)
}

🎯 Who Should Upgrade

• All production users - This release eliminates runtime panic risks
• Library integrators - Better error handling for invalid configurations
• Contributors - Clear guidelines for code contributions

📊 Performance

• No performance regressions
• Same sub-microsecond operation times
• Improved reliability under error conditions

🚀 Features Unchanged

All existing functionality remains the same:

• ✅ Production-ready rate limiting (token bucket, leaky bucket, distributed)
• ✅ Advanced concurrency limiters
• ✅ Enterprise-grade task scheduling with cron support
• ✅ High-performance streaming with backpressure control
• ✅ Comprehensive Prometheus metrics
• ✅ Multi-stage pipeline processing

🔗 Full Changelog

See CHANGELOG.md for complete version history.

---

Recommendation: Upgrade immediately for production safety. The API changes are minimal and improve reliability.

goflow v1.0.0 - Production-Ready Go Async/IO Toolkit

🚀 goflow v1.0.0 - Production-Ready Go Async/IO Toolkit

This is the first stable release of goflow, marking it as production-ready for building robust concurrent applications in Go.

🎯 What's New

🚀 Production-Ready Core Modules

• Advanced Rate Limiting (91.9-96.6% test coverage)
  • Token bucket, leaky bucket, and concurrency limiters
  • Distributed coordination with Redis backend
  • Sub-microsecond allow/deny decisions
• Enterprise Task Scheduling (85-95% test coverage)
  • Full cron expression support with timezone handling
  • Worker pools with dynamic scaling and graceful shutdown

  • 100K tasks/second sustained throughput

• High-Performance Streaming (84.6-95.0% test coverage)
  • Functional stream operations with backpressure control
  • Async writers optimized for high-volume operations
  • Multiple flow control strategies

🛡️ Enhanced Developer Experience

• Safe Constructors: NewSafe() functions return errors instead of panicking
• Structured Errors: ValidationError and OperationError types with actionable messages
• Comprehensive Documentation: Organized in /docs with getting started guides
• Production Examples: Complete web service integration demonstrating all modules

🔧 Technical Excellence

• Zero-Copy Operations: Efficient memory usage patterns
• Lock-Free Algorithms: Atomic operations where possible
• Context Integration: Sophisticated timeout and cancellation handling
• Graceful Shutdown: Proper resource cleanup and connection draining
• Full Observability: Prometheus metrics integration across all components

📊 Performance Benchmarks

Component	Performance	Allocations
Scheduler Operations	~1,636 ns/op	430 B/op, 6 allocs/op
Rate Limiting	Sub-microsecond	Minimal overhead
Worker Pool	>100K tasks/sec	Optimized for throughput

🧪 Quality Assurance

• ✅ All tests pass without race conditions or timeouts
• ✅ 85-96% test coverage across all modules
• ✅ No linting issues - clean codebase
• ✅ Production-tested integration patterns

📚 Documentation

• 📖 Getting Started Guide - New user onboarding
• 🏗️ Web Service Example - Complete integration
• 🛠️ Decision Guide - Component selection help
• 📚 API Documentation - Complete reference

🚀 Quick Start

go get github.com/vnykmshr/goflow

package main

import (
    "context"
    "log"

    "github.com/vnykmshr/goflow/pkg/ratelimit/bucket"
    "github.com/vnykmshr/goflow/pkg/scheduling/workerpool"
)

func main() {
    // Safe constructor with error handling
    limiter, err := bucket.NewSafe(100, 200) // 100 RPS, burst 200
    if err != nil {
        log.Fatal(err)
    }

    // Production-ready worker pool
    pool := workerpool.NewWithConfig(workerpool.Config{
        WorkerCount: 10,
        QueueSize:   1000,
    })
    defer func() { <-pool.Shutdown() }()

    // Your application logic here...
}

💯 Breaking Changes

None - This is the first stable release.

🔄 Migration Guide

This is the first stable release. See ./docs/GETTING_STARTED.md for comprehensive usage examples and best practices.

---
Full Changelog: https://github.com/vnykmshr/goflow/commits/v1.0.0