https://github.com/hungpdn/grule-plus
Fast, scalable and flexible rule engine for Go.
https://github.com/hungpdn/grule-plus
golang rule-based rule-engine scalability
Last synced: about 1 month ago
JSON representation
Fast, scalable and flexible rule engine for Go.
- Host: GitHub
- URL: https://github.com/hungpdn/grule-plus
- Owner: hungpdn
- Created: 2025-08-06T18:18:24.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-12-11T16:32:36.000Z (7 months ago)
- Last Synced: 2025-12-18T07:30:18.034Z (6 months ago)
- Topics: golang, rule-based, rule-engine, scalability
- Language: Go
- Homepage:
- Size: 45.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# grule-plus
[](https://golang.org/)
[](https://github.com/hungpdn/grule-plus/actions)
[](https://codecov.io/gh/hungpdn/grule-plus)
[](https://goreportcard.com/report/github.com/hungpdn/grule-plus)
[](https://opensource.org/licenses/MIT)
**grule-plus** is a high-performance, extensible rule engine built on top of [Grule Rule Engine](https://github.com/hyperjumptech/grule-rule-engine). It provides advanced caching, partitioning, and flexible configuration for scalable rule evaluation in Go applications.
---
## Features
- **Pluggable Cache Engines:** Supports LRU (Least Recently Used), LFU (Least Frequently Used), ARC (Adaptive Replacement Cache), and RANDOM cache strategies.
- **Partitioned Rule Engine:** Scale horizontally with partitioned engines for concurrent rule evaluation.
- **Consistent Hashing:** Efficient key distribution across partitions with minimal remapping on node changes.
- **Flexible TTL & Cleanup:** Per-rule time-to-live and periodic cleanup for cache entries.
- **Structured Logging:** Integrated with Go's `slog` for context-aware, structured logs.
- **Runtime Stats:** Built-in runtime statistics for monitoring and debugging.
- **Thread-Safe:** Safe for concurrent use in multi-goroutine environments.
---
## Benchmarks
Comprehensive benchmarks are available in the `benchmark/` directory, testing cache performance, engine throughput, and memory usage across different configurations. See [benchmark/README.md](benchmark/README.md) for detailed results and usage instructions.
---
## Getting Started
### Installation
```sh
go get github.com/hungpdn/grule-plus
```
### Example Usage
```go
import (
"context"
"github.com/hungpdn/grule-plus/engine"
)
func main() {
cfg := engine.Config{
Type: engine.LRU,
Size: 1000,
CleanupInterval: 10,
TTL: 60,
Partition: 1,
FactName: "DiscountFact",
}
grule := engine.NewPartitionEngine(cfg, nil)
rule := "DiscountRule"
statement := `rule DiscountRule "Apply discount" salience 10 {
when
DiscountFact.Amount > 100
then
DiscountFact.Discount = 10;
Retract("DiscountRule");
}`
_ = grule.AddRule(rule, statement, 60)
fact := struct {
Amount int
Discount int
}{Amount: 150}
_ = grule.Execute(context.Background(), rule, &fact)
fmt.Printf("fact.Discount = 10: %v", fact.Discount)
}
```
---
## Configuration
See `engine.Config` for all available options:
- `Type`: Cache type (LRU, LFU, ARC, TWOQ, RANDOM)
- `Size`: Maximum cache size
- `CleanupInterval`: Cache cleanup interval (seconds)
- `TTL`: Default time-to-live for rules (seconds)
- `Partition`: Number of partitions for parallelism
---
## Documentation
Comprehensive documentation is available in the `docs/` directory:
- **[API Reference](docs/api.md)** - Complete API documentation
- **[Architecture](docs/architecture.md)** - System design and components
- **[Cache Types](docs/cache-types.md)** - Cache algorithm explanations
- **[Configuration](docs/configuration.md)** - Setup and tuning guide
- **[Benchmarks](docs/benchmarks.md)** - Performance testing and results
- **[Examples](docs/examples.md)** - Usage patterns and code samples
### Building Documentation
```bash
# Install MkDocs (optional)
pip install mkdocs mkdocs-material
# Serve docs locally
cd docs && mkdocs serve
# Or use godoc for API docs
godoc -http=:6060
```
---
## Security
Please report security vulnerabilities by LinkedIn [**hungpdn**](https://www.linkedin.com/in/hungpdn/) (not through public issues). See [SECURITY.md](SECURITY.md) for details.
---
## TODO
- Metrics & Monitoring System (execution time, success/failure rates, cache hit/miss ratios, ...)
---
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.