feat: add configurable endpoint key granularity for reputation system #494
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add KeyGranularity config option to control how endpoints are grouped for reputation scoring: - per-endpoint: Each endpoint URL scored independently (default, finest) - per-supplier: All endpoints from same supplier share a score - per-service: All endpoints for a service share a single score (coarsest) Changes: - Add KeyBuilder interface with 3 implementations in reputation/key.go - Add KeyGranularity field to reputation.Config - Update ReputationService interface with KeyBuilder() method - Update protocol/shannon to use KeyBuilder for endpoint key creation - Add comprehensive tests (unit + integration) for all granularity levels - Update example config with key_granularity documentation
- Add per-domain key granularity to group endpoints by hosting domain (e.g., rm-01.eu.nodefleet.net -> eth:nodefleet.net) - Remove per-service granularity (blocking entire service not useful) - Add service_overrides config for per-service granularity settings - Change KeyBuilder() to KeyBuilderForService(serviceID) API - Fix style inconsistency in context.go endpoint address handling Granularity options (finest to coarsest): - per-endpoint: Each URL scored separately (default) - per-domain: Endpoints from same hosting domain share score - per-supplier: Endpoints from same supplier share score
7 tasks
oten91
approved these changes
Dec 4, 2025
oten91
added a commit
that referenced
this pull request
Dec 4, 2025
## Summary
Adds a probation system to the tiered endpoint selection, giving
low-scoring endpoints a chance to recover through limited traffic
sampling.
- **Probation Zone**: Endpoints scoring ≥10 but <30 (min threshold)
enter probation instead of being fully excluded
- **Traffic Sampling**: Only a configurable percentage (default 10%) of
requests consider probation endpoints
- **Recovery Multiplier**: Positive signals for probation endpoints are
boosted (default 2x) to accelerate score recovery
- **Metrics**: New Prometheus metrics for probation selection and
recovery multiplier application
### Score Hierarchy
```
Tier 1 (Premium): score >= 70
Tier 2 (Good): score >= 50
Tier 3 (Fair): score >= 30
Probation: score >= 10 but < 30
Excluded: score < 10
```
### New Metrics
- `shannon_reputation_probation_selection_total` - Probation endpoint
selection outcomes (selected/skipped)
- `shannon_reputation_recovery_multiplier_applied_total` - When recovery
multiplier boosts positive signals
### Configuration
```yaml
reputation_config:
tiered_selection:
probation:
enabled: true
threshold: 10 # Min score for probation (must be < min_threshold)
traffic_percent: 10 # % of requests that consider probation endpoints
recovery_multiplier: 2.0 # Boost factor for positive signals
```
## Depends On
- #494 (feat: add configurable endpoint key granularity for reputation
system)
## Test Plan
- [x] Unit tests for `TieredSelector.GroupByTierWithProbation()`
- [x] Unit tests for `TieredSelector.SelectEndpointWithProbation()` with
traffic sampling
- [x] Unit tests for recovery multiplier application in `RecordSignal()`
- [x] Config loading tests with probation settings
- [x] Local verification with live endpoint logging showing
`probation_threshold: 10`
- [x] `make test_unit` passes
- [x] `make go_lint` passes
includes #497
---------
Co-authored-by: Claude <[email protected]>
Co-authored-by: Otto V <[email protected]>
oten91
approved these changes
Dec 4, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Granularity Options
per-endpointeth:pokt1abc-https://node.comper-domaineth:nodefleet.netper-suppliereth:pokt1abc123Configuration
Changes
Test plan