Skip to content

feat: extract noteguard-core library crate#18

Open
alltheseas wants to merge 2 commits intodamus-io:masterfrom
alltheseas:feat/extract-noteguard-core
Open

feat: extract noteguard-core library crate#18
alltheseas wants to merge 2 commits intodamus-io:masterfrom
alltheseas:feat/extract-noteguard-core

Conversation

@alltheseas
Copy link

Summary

Extracts the core filtering logic into a standalone library crate (noteguard-core) that can be embedded in any Nostr relay, not just strfry.

  • New noteguard-core crate with filter registry, pipeline executor, and all built-in filters
  • noteguard binary refactored to be a thin stdin/stdout wrapper using noteguard-core
  • Updated README with library usage documentation

Motivation

This addresses #9 by making noteguard's filtering logic available as a library. Other relays (like notepush) can now embed noteguard filtering directly to prevent DoS attacks from spam that triggers expensive remote operations.

Using noteguard-core

[dependencies]
noteguard-core = { git = "https://github.com/damus-io/noteguard" }
use noteguard_core::{Noteguard, Config, Action};

let config: Config = toml::from_str(config_str)?;
let mut guard = Noteguard::new();
guard.load_config(&config)?;

let output = guard.run(input_message);
match output.action {
    Action::Accept => { /* process event */ },
    Action::Reject | Action::ShadowReject => { /* drop event */ },
}

Test plan

  • All existing tests pass (cargo test)
  • Binary builds and runs correctly
  • Library can be imported and used by downstream crates

🤖 Generated with Claude Code

Extracts the core filtering logic into a standalone library crate that
can be embedded in any Nostr relay, not just strfry.

## Changes

- New `noteguard-core` crate containing:
  - `Noteguard` struct: filter registry and pipeline executor
  - `NoteFilter` trait: interface for implementing filters
  - All built-in filters: ratelimit, whitelist, blacklist, kinds,
    content, protected_events, forwarder
  - `Config` struct for TOML configuration parsing

- `noteguard` binary refactored to be a thin wrapper that:
  - Reads from stdin (strfry protocol)
  - Delegates filtering to noteguard-core
  - Writes results to stdout

## Using noteguard-core

```toml
[dependencies]
noteguard-core = { git = "https://github.com/damus-io/noteguard" }
```

This enables other relays (like notepush) to embed noteguard filtering
directly, preventing DoS attacks from spam that triggers expensive
remote operations.

Addresses: damus-io#9

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
alltheseas added a commit to alltheseas/notepush that referenced this pull request Dec 12, 2025
Embeds noteguard-core filtering directly into notepush to prevent DoS
attacks from spam events that would trigger expensive remote operations
(mute list lookups, follow list fetches).

## Changes

- Add noteguard-core dependency (from alltheseas/noteguard branch until
  damus-io/noteguard#18 is merged)
- New event_filter.rs module bridges nostr::Event to noteguard-core
- EventFilter wraps Noteguard in Mutex for thread-safe concurrent access
- Filter pipeline runs in relay_connection.rs BEFORE notification processing
- Rate limiting keyed by pubkey (per-user limits)
- Graceful fallback: if no config exists, runs in permissive mode
- Added noteguard.toml.example with recommended configuration

## Integration flow

1. WebSocket receives EVENT message
2. Event runs through noteguard filter pipeline
3. If rejected: return error (or shadow-accept for spam hiding)
4. If accepted: proceed with notification logic

Resolves: #1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jb55
Copy link
Contributor

jb55 commented Dec 12, 2025

noteguard should be the library name, note noteguard_core

Per maintainer feedback, the library should be named `noteguard` not
`noteguard-core`. This restructures the crate to have both a library
(lib.rs) and binary (main.rs) in a single crate.

Users now import as:
  use noteguard::{Noteguard, Config, Action};

Changes:
- Move all filters from noteguard-core/src/ to src/
- Add lib.rs exposing the library API
- Update Cargo.toml to build both lib and bin targets
- Remove workspace configuration
- Update doc comments to reference noteguard instead of noteguard_core

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@alltheseas
Copy link
Author

alltheseas commented Dec 12, 2025

cca48d1

fixed in cca48d1

also updated notepush damus-io/notepush@3e742da accordingly

@alltheseas
Copy link
Author

@coderabbitai review please

@coderabbitai
Copy link

coderabbitai bot commented Jan 16, 2026

@alltheseas, I'll review the changes in this PR.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai
Copy link

coderabbitai bot commented Jan 16, 2026

Warning

Rate limit exceeded

@alltheseas has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 16 minutes and 36 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 4d4d9d6 and cca48d1.

⛔ Files ignored due to path filters (1)
  • Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing (14)
  • Cargo.toml
  • README.md
  • src/filters/blacklist.rs
  • src/filters/content.rs
  • src/filters/forwarder.rs
  • src/filters/kinds.rs
  • src/filters/mod.rs
  • src/filters/protected_events.rs
  • src/filters/ratelimit.rs
  • src/filters/whitelist.rs
  • src/lib.rs
  • src/main.rs
  • src/messages.rs
  • src/note_filter.rs

Comment @coderabbitai help to get the list of available commands and usage tips.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants