All notable changes to FURSY will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Future features and enhancements (Phase 4: Ecosystem)
0.4.0 - 2026-07-16
- Trailing Slash Handling — configurable via
WithTrailingSlash()(#6)IgnoreTrailingSlash(default):/usersand/users/are distinct routesStripTrailingSlash: silently serves the handler without redirectRedirectTrailingSlash: 301 (GET) or 308 (other methods) redirect to canonical URL- Bidirectional: handles both adding and removing trailing slashes
- Query strings preserved across redirects
- 405 Method Not Allowed correctly considers alternate paths
- 100% test coverage on all new functions (16 test functions, 43 test cases, 2 benchmarks)
- ResponseWriter missing http.Flusher — all ResponseWriter wrappers now implement
http.FlusherandUnwrap()(#7)- Logger, CircuitBreaker, OpenTelemetry tracing, and OpenTelemetry metrics wrappers
- SSE streaming (
text/event-stream) now works correctly with middleware enabled Flush()delegates to underlying ResponseWriter;Unwrap()returns the original (Go 1.20+ convention)
- ServeHTTP refactored: extracted
handleNotFound(),tryTrailingSlashLookup(),existsInTree()for reduced cognitive complexity and better maintainability - Lint cleanup: resolved all 48 pre-existing golangci-lint issues (goconst, govet inline)
- Test Coverage: 93.8% → 94.6% (+0.8%)
- Exact match with trailing slash enabled: 142 ns/op, 1 alloc/op (near-zero overhead vs baseline 131 ns)
- Strip trailing slash (fallback path): 240 ns/op, 2 allocs/op (well under 500ns target)
0.3.4 - 2026-03-05
- Test Coverage: Comprehensive test coverage improvements for awesome-go submission
- Total coverage: 90.1% → 93.8% (+3.7%)
- Core (
fursy): 93.1% → 94.3% (+1.2%) - Binding (
internal/binding): 64.4% → 97.7% (+33.3%) - Middleware: 91.7% → 95.6% (+3.9%)
- Binding Tests: Full coverage for
setField(all Go types: int8-64, uint8-64, float32/64, bool, string),mapFormedge cases (non-pointer, non-struct, unexported fields, missing values), XML/multipart binder error paths - Box Tests: Tests for
Unauthorized()andForbidden()response methods - Generic Router Tests: Tests for
HEAD[Req,Res]()andOPTIONS[Req,Res]()(new filerouter_generic_test.go) - OpenAPI Tests: Tests for
WriteJSON()(Content-Type, body validation) andWriteYAML()(not-implemented error) - CircuitBreaker Tests: Tests for
CircuitBreaker()default constructor,CircuitBreakerWithName(),GetState(),GetCounts(),Reset(),FormatState() - Middleware Tests: Tests for
Logger()andRecovery()default constructors
- README.md: Fixed 5 critical API mismatches between documentation and actual code
JWT()signature: was showing config struct, corrected toJWT(signingKey)/JWTWithConfig(config)RateLimit()signature: was showing config struct, corrected toRateLimit(rate, burst)/RateLimitWithConfig(config)CircuitBreaker()signature: removed non-existent fields (ResetTimeout,FailureRatio), added helper functionsrouter.Run(): replaced withhttp.ListenAndServe()(Run method does not exist)- Package godoc: fixed
*fursy.Boxwithout type params →*fursy.Context
- All tests passing, 0 linter issues (golangci-lint clean)
- No performance regressions
0.3.3 - 2025-11-24
- Critical Routing Bug: Fixed panic in routes with
:paramfollowed by multiple static segments- Routes like
/users/:id/activate+/users/:id/deactivatewould panic at line 147 - Root cause: Common prefix check compared
/deactivatewith:idand found no match - Solution: Implemented httprouter's approach of creating empty placeholder child nodes after param nodes
- Pattern studied from httprouter's
insertChild(lines 217-270) andaddRoute(lines 180-184) - Changed files:
internal/radix/tree.go(lines 118-138): Added special case handling for param node childreninternal/radix/tree_param_static_test.go(new file): 6 comprehensive test cases covering all param+static patterns
- Routes like
- All 650+ tests passing with race detector (via WSL2 Gentoo)
- New test cases (all passing):
TestTree_ParamWithMultipleStaticChildren- Original bug case (/users/:id/activate+/users/:id/deactivate)TestTree_NestedParams- Nested params (/users/:user_id/posts/:post_id/comments)TestTree_AlternatingParamStatic- Alternating pattern (/a/:b/c/:d/e)TestTree_ParamWithLongStaticTail- Long static tails (/:a/b/c/d/e/f/g)TestTree_ConsecutiveParams- Consecutive params (/:a/:b/:c/d)TestTree_StaticVsParam- Static priority over params
- Coverage: 88.4% internal/radix, 91.7% overall (maintained high quality)
- Linter: 0 issues (golangci-lint clean)
- No regressions - routing performance maintained:
- Static routes: 256 ns/op, 1 alloc/op
- Parametric routes: 326 ns/op, 1 alloc/op
- httprouter Pattern: When param node has static children, create empty placeholder child (path="", priority=1) and bypass common prefix check
- Direct Assignment: Use
n.children = []*node{child}instead ofaddChild()to allow empty path placeholder - Zero-allocation Routing: Placeholder pattern maintains zero-allocation guarantee for route lookup
0.3.2 - 2025-11-19
- Minimal Dependencies Policy: Removed SQLite from core dependencies
- Deleted redundant
plugins_integration_test.gofrom root (integration tests already inplugins/database/) - Core now has ONLY 2 external dependencies:
golang-jwt/jwt(JWT middleware) andgolang.org/x/time(RateLimit middleware) - Removed ~10 transitive dependencies from core module (dustin/go-humanize, google/uuid, modernc.org/sqlite, etc.)
- SQLite remains available in
plugins/databasefor users who need it
- Deleted redundant
- Coverage: 91.7% (maintained high quality after cleanup)
- Tests: All passing with race detector
- Performance: No regressions (256 ns/op static, 326 ns/op parametric)
0.3.1 - 2025-11-19
- Build Issues: Fixed issues in v0.3.0 cached in proxy.golang.org
- Removed local path replace directive from go.mod (fixes CI failures)
- Deleted broken
examples/09-rest-api-with-db/main.go(syntax errors) - Applied code formatting with gofmt to all files
- Cleaned up go.mod dependencies
v0.3.1 is a patch release fixing deployment issues in v0.3.0. Use v0.3.2 for the cleanest version.
0.3.0 - 2025-11-19
- Stream Library Integration: Official
plugins/streamfor SSE and WebSocket supportSSEHub[T]middleware for type-safe Server-Sent Events broadcastingWebSocketHubmiddleware for WebSocket connection management- Context helpers:
stream.SSEUpgrade(),stream.WebSocketUpgrade() - Type-safe helpers:
stream.GetSSEHub[T](),stream.GetWebSocketHub() - Integration with
github.com/coregx/streamv0.1.0 (314 tests, 84.3% coverage) - 83.3% test coverage (13 tests, 700+ lines)
- Database Plugin: Official
plugins/databasefor database/sql integrationMiddleware()for injecting database into request contextTxMiddleware()for automatic transaction management- Context helper:
c.DB()for convenient database access - Enhanced helpers:
MustGetDB(),GetDBOrError(),MustGetTx(),GetTxOrError() - dbcontext pattern with 3 approaches (production-ready + prototyping + custom)
- Repository pattern integration examples
- Transaction support:
BeginTx(),Commit(),Rollback(),WithTx() - Pure Go SQLite support (modernc.org/sqlite, no CGO)
- Works with any database/sql driver (PostgreSQL, MySQL, SQLite, SQL Server)
- 89.7% test coverage (17 tests including CRUD integration test)
- Complete DDD Example: Domain-Driven Design production reference implementation
- Domain-Driven Design with Rich Models (User entity with business logic)
- Clean Architecture: domain/application/infrastructure/interfaces layers
- Value Objects: Email, Password, Role, Status (enforcing invariants)
- User management module:
- Registration with password hashing (bcrypt)
- JWT authentication (login, token refresh)
- Profile management (get, update, delete)
- Role-based authorization (user/admin)
- Real-time features:
- Server-Sent Events for notifications
- WebSocket chat (with join/leave messages)
- Multi-client broadcasting
- Database:
- SQLite with migrations
- Transaction support
- Repository pattern
- Infrastructure:
- Docker support (Dockerfile + docker-compose.yml)
- Graceful shutdown (signal handling)
- Structured logging (log/slog)
- RFC 9457 error responses
- Testing:
- 36 comprehensive tests (1,766 lines)
- 60.6% test coverage
- Unit tests for all layers
- Integration tests for API endpoints
- Complete README (14.8KB, API documentation, setup instructions)
- SSE Notifications:
examples/07-sse-notifications- Real-time server push- Multi-client notification hub
- POST endpoint to broadcast notifications
- Complete working example
- WebSocket Chat:
examples/08-websocket-chat- Bidirectional communication- Real-time chat server with broadcasting
- HTML/CSS/JS web client included
- Join/leave notifications
- Username support
- Database CRUD:
examples/09-rest-api-with-db- Database integration- Complete REST API with SQLite
- CRUD operations (Create, Read, Update, Delete)
- Transaction examples
- Error handling with RFC 9457
- Examples Navigation:
examples/README.mdwith learning path- 10 total examples (from basic to production)
- Progressive learning path (Beginner → Intermediate → Advanced)
- Quick navigation table
- Common patterns reference
- Plugin Integration Methods in Context:
c.DB()- Access database connection (requires plugins/database)c.SSE()stub method - Returns ErrStreamNotImported if plugin not usedc.WebSocket()stub method - Returns ErrStreamNotImported if plugin not used- New error:
ErrStreamNotImportedfor clear error messages - 4 integration tests in
context_integration_test.go
- Coverage: Increased from 88.9% to 93.1% overall (+4.2%)
- Core: 93.1% (maintained high quality)
- plugins/database: 89.7% (17 tests)
- plugins/stream: 83.3% (13 tests)
- examples/10-production-boilerplate: 60.6% (36 tests)
- Test Count: Added 70+ tests across new features
- Database: 17 tests
- Stream plugin: 13 tests
- Production boilerplate: 36 tests
- Integration: 4 tests
- Total: 650+ tests across all packages
- Dependencies: Added
github.com/coregx/streamas ecosystem dependency- Core routing: Still ZERO dependencies (stdlib only)
- Stream plugin: Depends on github.com/coregx/stream v0.1.0
- Database plugin: Zero external dependencies (database/sql only)
- stream v0.1.0 Released: Companion library for real-time communications
- SSE: 92.3% coverage, 61 tests, RFC text/event-stream compliant
- WebSocket: 84.3% coverage, 253 tests, RFC 6455 compliant
- Zero external dependencies (pure stdlib)
- High performance: 11 μs/op (10 WS clients), 8 μs/op (10 SSE clients)
- Production-ready with comprehensive documentation
- README.md: Updated with v0.3.0 features
- New "Plugin Integration Methods" section
- Real-time communications examples
- Database integration patterns
- Updated version badges (v0.3.0, 93.1% coverage)
- Updated roadmap with v0.3.0 completion
- Plugin Documentation:
plugins/database/README.md- Complete database integration guide (558 lines)plugins/stream/README.md- Complete stream integration guide (373 lines)- dbcontext pattern with 3 approaches
- Repository pattern integration
- Best practices and examples
- Examples Documentation:
examples/README.md- Navigation guide with learning path (121 lines)examples/10-production-boilerplate/README.md- Production guide (14.8KB)- Progressive learning path (Beginner → Intermediate → Advanced)
- Maintained Routing Performance: 256 ns/op (static), 326 ns/op (parametric)
- Real-time Performance (via stream v0.1.0):
- SSE Hub broadcast (10 clients): 8 μs/op
- WebSocket Hub broadcast (10 clients): 11 μs/op
- All benchmarks validated and documented
- No performance regressions
- Total Tests: 650+ across all packages (up from ~580)
- Coverage:
- Core: 93.1% (maintained high quality)
- Database plugin: 89.7%
- Stream plugin: 83.3%
- Production boilerplate: 60.6%
- Comprehensive integration tests for all new features
- Production boilerplate demonstrates testing best practices (1,766 lines of tests)
- Enhanced by Claude (fursy-senior-architect agent)
0.2.0 - 2025-11-18
Validator Plugin
- New
plugins/validatorpackage with go-playground/validator/v10 integration - Automatic request validation with 100+ validation tags
- RFC 9457 Problem Details error conversion
- 40+ default error messages for common validation tags
- Custom error messages support
- 94.3% test coverage
Documentation Enhancements
- Middleware Section in README.md (288 lines)
- All 8 built-in middleware documented with examples
- Configuration options for each middleware
- Comparison table vs Gin/Echo/Fiber
- OPUS visibility fix - all middleware now discoverable
- Automatic Validation Section in README.md
- Complete guide to request validation
- Type-safe Box[Req, Res] validation examples
- RFC 9457 error responses
- Comparison with other routers
- Content Negotiation Section in README.md
- RFC 9110 compliant content negotiation
- AI agent support (text/markdown)
- Q-value priority examples
- Multi-format response examples
- Observability Section in README.md
- OpenTelemetry integration guide
- Distributed tracing with Jaeger
- Metrics collection with Prometheus
- Custom spans examples
- llms.md - Complete guide for AI agents (1,716 lines)
- Project architecture and structure
- Development standards (encoding/json/v2, log/slog, minimal deps)
- Testing requirements and git workflow
- All 8 middleware documented
- Common gotchas with fixes
- Contributing guidelines
Examples (11 Total)
- Basic Examples
01-hello-world- Minimal fursy application (<30 lines)02-rest-api-crud- Complete CRUD API (385 lines)
- Advanced Examples
04-content-negotiation- Multi-format responses (1,507 lines)- Accepts(), AcceptsAny(), Markdown() methods
- Q-value priority handling
- AI agent friendly responses
05-middleware- All middleware + custom patterns (1,512 lines)- All 8 built-in middleware demonstrated
- 8 custom middleware patterns
- Production-ready configurations
06-opentelemetry- Distributed tracing (1,270 lines)- OTLP/HTTP integration with Jaeger
- Custom spans for DB queries and external calls
- Docker Compose for Jaeger + Prometheus
- 7 endpoints demonstrating tracing patterns
- Validation Examples (6 examples in validation/ directory)
validation/01-basic- Simple validation demovalidation/02-rest-api-crud- Full CRUD with validatorvalidation/03-custom-validator- Custom validation functionsvalidation/04-nested-structs- Nested struct validationvalidation/05-custom-messages- Custom error messagesvalidation/06-production- Production-ready setup
- Examples Index
examples/README.md- Navigation guide (602 lines)- Progressive learning path (Beginner → Intermediate → Advanced)
- Total learning time: ~3.5 hours
Developer Experience
- Progressive learning path from basic to advanced (11 examples)
- Complete navigation guide in examples/README.md
- AI agent friendly documentation (llms.md)
- All middleware now visible in README (OPUS discoverability fix)
Statistics
- 7,000+ lines of documentation added
- 5,000+ lines of example code
- 11 complete working examples
- 3 new plugins documented (Validator, OpenTelemetry, Metrics)
Updated Files
- README.md - Added 4 major sections (Middleware, Validation, Content Negotiation, Observability)
- llms.md - Created comprehensive AI agent guide
- examples/README.md - Created examples navigation index
Coverage
- All 8 middleware now documented
- All public APIs documented with examples
- Production patterns demonstrated in examples
0.1.0 - 2025-11-16
Core HTTP Router
- High-performance HTTP router with radix tree algorithm
- Support for three route types:
- Static routes:
/users - Named parameters:
/users/:id - Wildcard routes:
/files/*path
- Static routes:
- All standard HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
- Generic
Handle(method, path, handler)for custom methods
Context API
- Context-based request/response handling
- URL parameter extraction:
Param(key) - Query parameter helpers:
Query(),QueryDefault(),QueryValues() - Form parameter helpers:
Form(),FormDefault(),PostForm() - Data storage for middleware:
Get(),Set(),GetString(),GetInt(),GetBool()
Response Helpers
- Explicit methods (full control):
String(code, text)- Text responsesJSON(code, data)- JSON serialization (usesencoding/json/v2)JSONIndent(code, data, indent)- Pretty JSONXML(code, data)- XML serializationNoContent(code)- Empty responsesRedirect(code, url)- HTTP redirects (301, 302, 307, 308)Blob(code, contentType, data)- Binary responsesStream(code, contentType, reader)- Streaming responsesError(status, problem)- RFC 9457 Problem Details responses
- Convenience methods (REST best practices):
OK(obj)- 200 OK JSON responseCreated(obj)- 201 Created (POST best practice)Accepted(obj)- 202 Accepted (async operations)NoContentSuccess()- 204 No Content (DELETE best practice)Text(s)- 200 OK plain text response
HTTP Headers
SetHeader(key, value)- Set response headersGetHeader(key)- Get request headers
Middleware
- Middleware pipeline with
Next()andAbort()pattern - Pre-allocated handlers buffer (capacity 16)
- Route groups with nested middleware inheritance
- JWT Authentication middleware (94.2% coverage)
- Rate Limiting middleware (94.4% coverage, token bucket algorithm)
- Security Headers middleware (100% coverage, OWASP 2025 compliant)
- Circuit Breaker middleware (95.5% coverage, zero dependencies)
- Recovery middleware (panic recovery)
- Logger middleware (structured logging with
log/slog) - CORS middleware (Cross-Origin Resource Sharing)
Performance Optimizations
- Context pooling with
sync.Pool- 1 alloc/op - Radix tree routing: 256 ns/op static, 326 ns/op parametric
- Zero-allocation parameter extraction
- Pre-allocated buffers (params: 8, handlers: 16)
- Memory leak prevention (max capacity limits: 32/64)
- Efficient memory usage (~10M req/s throughput)
Error Handling
- RFC 9457 Problem Details - Standardized error responses
- Automatic 404 Not Found for unregistered routes
- Automatic 405 Method Not Allowed (configurable)
- Error propagation from handlers
- Predefined errors:
ErrInvalidRedirectCode - Helper functions:
BadRequest(),Unauthorized(),Forbidden(),NotFound(), etc.
Production Features
- Graceful Shutdown - Connection draining, signal handling (SIGTERM, SIGINT)
- Circuit Breaker - Failure threshold, auto-recovery, zero dependencies
- Rate Limiting - Token bucket, per-IP/per-user, configurable limits
- Security Headers - CSP, HSTS, X-Frame-Options, X-Content-Type-Options
- JWT Authentication - Token validation, claims extraction, secure defaults
Testing & Quality
- Comprehensive test suite: 100+ test functions, 300+ test cases
- 91.7% overall test coverage (exceeded Phase 2 target of 88%)
- Race condition testing with
-raceflag (all tests pass) - Benchmark suite with 19 benchmarks
- Memory allocation tracking (1 alloc/op routing hot path)
- golangci-lint configuration with 34+ enabled linters
- Pre-release check script (
scripts/pre-release-check.sh) - Cross-platform testing (Linux, macOS, Windows)
Documentation
- Complete package documentation with examples
- godoc comments on all exported types and functions
- README.md with quick start guide
- CHANGELOG.md (this file)
- CONTRIBUTING.md - Development workflow and git-flow
- RELEASE_GUIDE.md - Release process documentation
- SECURITY.md - Security policy and best practices
- PERFORMANCE.md - Detailed benchmark results and optimization guide
- ROADMAP.md - Project roadmap and version strategy
- Example code for all major features
Benchmarks (on Intel Core i7-1255U, 12th Gen):
- Static routes: 256 ns/op, 1 alloc/op, ~10.5M ops/s
- Parametric routes: 326 ns/op, 1 alloc/op, ~7.2M ops/s
- Multiple params: 344 ns/op, 1 alloc/op, ~6.3M ops/s
- Deep nesting (4 params): 561 ns/op, 1 alloc/op, ~4.0M ops/s
- Wildcard routes: 539 ns/op, 1 alloc/op, ~7.8M ops/s
- Context.Param(): 3.7 ns/op, 0 allocs/op
- Context.Query(): 21.8 ns/op, 0 allocs/op
- Middleware chain: 1805 ns/op, 11 allocs/op, ~1.7M ops/s
Coverage:
- Overall: 91.7% (exceeded Phase 1 target of 85%)
- Security middleware: 94-100%
- Circuit breaker: 95.5%
- JWT authentication: 94.2%
- Rate limiting: 94.4%
See PERFORMANCE.md for detailed results.
Dependencies:
- Minimal external dependencies - Core routing: stdlib only
- Middleware dependencies: JWT (
golang-jwt/jwt/v5), Rate Limiting (golang.org/x/time) - Go 1.25+ required (uses generics and modern features)
- Uses standard library v2:
encoding/json/v2,log/slog - Standard library:
net/http,encoding/xml,sync,time - Plugins (optional) may have additional dependencies
Architecture:
- Clean separation: public API (fursy) wraps internal implementation (internal/radix)
- Radix tree routing algorithm (based on httprouter design)
- Context pooling pattern for performance
- Interface-based design for extensibility
- Initial release, no breaking changes
- API is production-ready but may evolve in 0.x versions
- v1.0.0 will guarantee API stability (planned Q3 2026)
This release represents Phase 0-3 completion:
- Phase 0: Project setup, CI/CD, documentation infrastructure
- Phase 1: Foundation - Radix tree routing, basic middleware, route groups
- Phase 2: API Excellence - RFC 9457, improved error handling
- Phase 3: Production Features - Auth, rate limiting, circuit breaker, pooling
Next Steps (v0.2.0+):
- Additional middleware (Database, Cache)
- Documentation website (fursy.coregx.dev)
- Migration guides from popular frameworks
- Community building and feedback
Version Strategy:
- 0.y.0 - New features (e.g., v0.2.0, v0.3.0)
- 0.y.z - Bug fixes, hotfixes
- v1.0.0 - Long-term API stability (Q3 2026, after 6-12 months production validation)
This is the first production-ready release of FURSY. All core features are complete:
- ✅ Generic type-safe handlers with
Box[Req, Res] - ✅ Middleware pipeline system with Next/Abort pattern
- ✅ RFC 9457 Problem Details for standardized errors
- ✅ OpenAPI 3.1 specification generation (built-in)
- ✅ Route groups with nested middleware inheritance
- ✅ High-performance routing (256-326 ns/op, 1 alloc/op)
- ✅ Production features (JWT, Rate Limiting, Circuit Breaker, Security Headers)
- ✅ Convenience methods for REST best practices
- ✅ 91.7% test coverage
See ROADMAP.md for future ecosystem features (v0.2.0+).
v0.2.0+ (Feature Releases) - As features are ready:
- Database middleware (PostgreSQL, MySQL, SQLite)
- Cache middleware (Redis, Memcached)
- Additional plugins and integrations
- Community-requested features
v1.0.0 LTS - After 6-12+ months of production usage:
- API stability guarantees
- Long-term support (3+ years)
- Enterprise-grade reliability
- No breaking changes in v1.x.x
See ROADMAP.md for detailed plans and timelines.