Browse Source
- Add ORLY_POLICY_PATH environment variable to configure custom policy file path, overriding the default ~/.config/ORLY/policy.json location - Enforce ABSOLUTE paths only - relay panics on startup if relative path is provided, preventing common misconfiguration errors - Update PolicyManager to store and expose configPath for hot-reload saves - Add ConfigPath() method to P struct delegating to internal PolicyManager - Update NewWithManager() signature to accept optional custom path parameter - Add BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md with issue submission guidelines requiring environment details, reproduction steps, and logs - Update README.md with system requirements (500MB minimum memory) and link to bug report protocol - Update CLAUDE.md and README.md documentation for new ORLY_POLICY_PATH Files modified: - app/config/config.go: Add PolicyPath config field - pkg/policy/policy.go: Add configPath storage and validation - app/handle-policy-config.go: Use policyManager.ConfigPath() - app/main.go: Pass cfg.PolicyPath to NewWithManager - pkg/policy/*_test.go: Update test calls with new parameter - BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md: New file - README.md, CLAUDE.md: Documentation updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>main
mleku
4 weeks ago
17 changed files with 335 additions and 20 deletions
@ -0,0 +1,254 @@ |
|||||||
|
# Feature Request and Bug Report Protocol |
||||||
|
|
||||||
|
This document describes how to submit effective bug reports and feature requests for ORLY relay. Following these guidelines helps maintainers understand and resolve issues quickly. |
||||||
|
|
||||||
|
## Before Submitting |
||||||
|
|
||||||
|
1. **Search existing issues** - Your issue may already be reported or discussed |
||||||
|
2. **Check documentation** - Review `CLAUDE.md`, `docs/`, and `pkg/*/README.md` files |
||||||
|
3. **Verify with latest version** - Ensure the issue exists in the current release |
||||||
|
4. **Test with default configuration** - Rule out configuration-specific problems |
||||||
|
|
||||||
|
## Bug Reports |
||||||
|
|
||||||
|
### Required Information |
||||||
|
|
||||||
|
**Title**: Concise summary of the problem |
||||||
|
- Good: "Kind 3 events with 8000+ follows truncated on save" |
||||||
|
- Bad: "Events not saving" or "Bug in database" |
||||||
|
|
||||||
|
**Environment**: |
||||||
|
``` |
||||||
|
ORLY version: (output of ./orly version) |
||||||
|
OS: (e.g., Ubuntu 24.04, macOS 14.2) |
||||||
|
Go version: (output of go version) |
||||||
|
Database backend: (badger/neo4j/wasmdb) |
||||||
|
``` |
||||||
|
|
||||||
|
**Configuration** (relevant settings only): |
||||||
|
```bash |
||||||
|
ORLY_DB_TYPE=badger |
||||||
|
ORLY_POLICY_ENABLED=true |
||||||
|
# Include any non-default settings |
||||||
|
``` |
||||||
|
|
||||||
|
**Steps to Reproduce**: |
||||||
|
1. Start relay with configuration X |
||||||
|
2. Connect client and send event Y |
||||||
|
3. Query for event with filter Z |
||||||
|
4. Observe error/unexpected behavior |
||||||
|
|
||||||
|
**Expected Behavior**: What should happen |
||||||
|
|
||||||
|
**Actual Behavior**: What actually happens |
||||||
|
|
||||||
|
**Logs**: Include relevant log output with `ORLY_LOG_LEVEL=debug` or `trace` |
||||||
|
|
||||||
|
### Minimal Reproduction |
||||||
|
|
||||||
|
The most effective bug reports include a minimal reproduction case: |
||||||
|
|
||||||
|
```bash |
||||||
|
# Example: Script that demonstrates the issue |
||||||
|
export ORLY_LOG_LEVEL=debug |
||||||
|
./orly & |
||||||
|
sleep 2 |
||||||
|
|
||||||
|
# Send problematic event |
||||||
|
echo '["EVENT", {...}]' | websocat ws://localhost:3334 |
||||||
|
|
||||||
|
# Show the failure |
||||||
|
echo '["REQ", "test", {"kinds": [1]}]' | websocat ws://localhost:3334 |
||||||
|
``` |
||||||
|
|
||||||
|
Or provide a failing test case: |
||||||
|
|
||||||
|
```go |
||||||
|
func TestReproduceBug(t *testing.T) { |
||||||
|
// Setup |
||||||
|
db := setupTestDB(t) |
||||||
|
|
||||||
|
// This should work but fails |
||||||
|
event := createTestEvent(kind, content) |
||||||
|
err := db.SaveEvent(ctx, event) |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
// Query returns unexpected result |
||||||
|
results, err := db.QueryEvents(ctx, filter) |
||||||
|
assert.Len(t, results, 1) // Fails: got 0 |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
## Feature Requests |
||||||
|
|
||||||
|
### Required Information |
||||||
|
|
||||||
|
**Title**: Clear description of the feature |
||||||
|
- Good: "Add WebSocket compression support (permessage-deflate)" |
||||||
|
- Bad: "Make it faster" or "New feature idea" |
||||||
|
|
||||||
|
**Problem Statement**: What problem does this solve? |
||||||
|
``` |
||||||
|
Currently, clients with high-latency connections experience slow sync times |
||||||
|
because event data is transmitted uncompressed. A typical session transfers |
||||||
|
50MB of JSON that could be reduced to ~10MB with compression. |
||||||
|
``` |
||||||
|
|
||||||
|
**Proposed Solution**: How should it work? |
||||||
|
``` |
||||||
|
Add optional permessage-deflate WebSocket extension support: |
||||||
|
- New config: ORLY_WS_COMPRESSION=true |
||||||
|
- Negotiate compression during WebSocket handshake |
||||||
|
- Apply to messages over configurable threshold (default 1KB) |
||||||
|
``` |
||||||
|
|
||||||
|
**Use Case**: Who benefits and how? |
||||||
|
``` |
||||||
|
- Mobile clients on cellular connections |
||||||
|
- Users syncing large follow lists |
||||||
|
- Relays with bandwidth constraints |
||||||
|
``` |
||||||
|
|
||||||
|
**Alternatives Considered** (optional): |
||||||
|
``` |
||||||
|
- Application-level compression: Rejected because it requires client changes |
||||||
|
- HTTP/2: Not applicable for WebSocket connections |
||||||
|
``` |
||||||
|
|
||||||
|
### Implementation Notes (optional) |
||||||
|
|
||||||
|
If you have implementation ideas: |
||||||
|
|
||||||
|
``` |
||||||
|
Suggested approach: |
||||||
|
1. Add compression config to app/config/config.go |
||||||
|
2. Modify gorilla/websocket upgrader in app/handle-websocket.go |
||||||
|
3. Add compression threshold check before WriteMessage() |
||||||
|
|
||||||
|
Reference: gorilla/websocket has built-in permessage-deflate support |
||||||
|
``` |
||||||
|
|
||||||
|
## What Makes Reports Effective |
||||||
|
|
||||||
|
**Do**: |
||||||
|
- Be specific and factual |
||||||
|
- Include version numbers and exact error messages |
||||||
|
- Provide reproducible steps |
||||||
|
- Attach relevant logs (redact sensitive data) |
||||||
|
- Link to related issues or discussions |
||||||
|
- Respond to follow-up questions promptly |
||||||
|
|
||||||
|
**Avoid**: |
||||||
|
- Vague descriptions ("it doesn't work") |
||||||
|
- Multiple unrelated issues in one report |
||||||
|
- Assuming the cause without evidence |
||||||
|
- Demanding immediate fixes |
||||||
|
- Duplicating existing issues |
||||||
|
|
||||||
|
## Issue Labels |
||||||
|
|
||||||
|
When applicable, suggest appropriate labels: |
||||||
|
|
||||||
|
| Label | Use When | |
||||||
|
|-------|----------| |
||||||
|
| `bug` | Something isn't working as documented | |
||||||
|
| `enhancement` | New feature or improvement | |
||||||
|
| `performance` | Speed or resource usage issue | |
||||||
|
| `documentation` | Docs are missing or incorrect | |
||||||
|
| `question` | Clarification needed (not a bug) | |
||||||
|
| `good first issue` | Suitable for new contributors | |
||||||
|
|
||||||
|
## Response Expectations |
||||||
|
|
||||||
|
- **Acknowledgment**: Within a few days |
||||||
|
- **Triage**: Issue labeled and prioritized |
||||||
|
- **Resolution**: Depends on complexity and priority |
||||||
|
|
||||||
|
Complex features may require discussion before implementation. Bug fixes for critical issues are prioritized. |
||||||
|
|
||||||
|
## Following Up |
||||||
|
|
||||||
|
If your issue hasn't received attention: |
||||||
|
|
||||||
|
1. **Check issue status** - It may be labeled or assigned |
||||||
|
2. **Add new information** - If you've discovered more details |
||||||
|
3. **Politely bump** - A single follow-up comment after 2 weeks is appropriate |
||||||
|
4. **Consider contributing** - PRs that fix bugs or implement features are welcome |
||||||
|
|
||||||
|
## Contributing Fixes |
||||||
|
|
||||||
|
If you want to fix a bug or implement a feature yourself: |
||||||
|
|
||||||
|
1. Comment on the issue to avoid duplicate work |
||||||
|
2. Follow the coding patterns in `CLAUDE.md` |
||||||
|
3. Include tests for your changes |
||||||
|
4. Keep PRs focused on a single issue |
||||||
|
5. Reference the issue number in your PR |
||||||
|
|
||||||
|
## Security Issues |
||||||
|
|
||||||
|
**Do not report security vulnerabilities in public issues.** |
||||||
|
|
||||||
|
For security-sensitive bugs: |
||||||
|
- Contact maintainers directly |
||||||
|
- Provide detailed reproduction steps privately |
||||||
|
- Allow reasonable time for a fix before disclosure |
||||||
|
|
||||||
|
## Examples |
||||||
|
|
||||||
|
### Good Bug Report |
||||||
|
|
||||||
|
```markdown |
||||||
|
## WebSocket disconnects after 60 seconds of inactivity |
||||||
|
|
||||||
|
**Environment**: |
||||||
|
- ORLY v0.34.5 |
||||||
|
- Ubuntu 22.04 |
||||||
|
- Go 1.25.3 |
||||||
|
- Badger backend |
||||||
|
|
||||||
|
**Steps to Reproduce**: |
||||||
|
1. Connect to relay: `websocat ws://localhost:3334` |
||||||
|
2. Send subscription: `["REQ", "test", {"kinds": [1], "limit": 1}]` |
||||||
|
3. Wait 60 seconds without sending messages |
||||||
|
4. Observe connection closed |
||||||
|
|
||||||
|
**Expected**: Connection remains open (Nostr relays should maintain persistent connections) |
||||||
|
|
||||||
|
**Actual**: Connection closed with code 1000 after exactly 60 seconds |
||||||
|
|
||||||
|
**Logs** (ORLY_LOG_LEVEL=debug): |
||||||
|
``` |
||||||
|
1764783029014485🔎 client timeout, closing connection /app/handle-websocket.go:142 |
||||||
|
``` |
||||||
|
|
||||||
|
**Possible Cause**: May be related to read deadline not being extended on subscription activity |
||||||
|
``` |
||||||
|
|
||||||
|
### Good Feature Request |
||||||
|
|
||||||
|
```markdown |
||||||
|
## Add rate limiting per pubkey |
||||||
|
|
||||||
|
**Problem**: |
||||||
|
A single pubkey can flood the relay with events, consuming storage and |
||||||
|
bandwidth. Currently there's no way to limit per-author submission rate. |
||||||
|
|
||||||
|
**Proposed Solution**: |
||||||
|
Add configurable rate limiting: |
||||||
|
```bash |
||||||
|
ORLY_RATE_LIMIT_EVENTS_PER_MINUTE=60 |
||||||
|
ORLY_RATE_LIMIT_BURST=10 |
||||||
|
``` |
||||||
|
|
||||||
|
When exceeded, return OK false with "rate-limited" message per NIP-20. |
||||||
|
|
||||||
|
**Use Case**: |
||||||
|
- Public relays protecting against spam |
||||||
|
- Community relays with fair-use policies |
||||||
|
- Paid relays enforcing subscription tiers |
||||||
|
|
||||||
|
**Alternatives Considered**: |
||||||
|
- IP-based limiting: Ineffective because users share IPs and use VPNs |
||||||
|
- Global limiting: Punishes all users for one bad actor |
||||||
|
``` |
||||||
Loading…
Reference in new issue