next.orly.dev/scripts/sprocket/SPROCKET_TEST_README.md

Sprocket Test Suite

This directory contains a comprehensive test suite for the ORLY relay's sprocket event processing system.

Overview

The sprocket system allows external scripts to process Nostr events before they are stored in the relay. Events are sent to the sprocket script via stdin, and the script responds with JSONL messages indicating whether to accept, reject, or shadow reject the event.

Test Files

Core Test Files

• test-sprocket.py - Python sprocket script that implements various filtering criteria
• test-sprocket-integration.go - Go integration tests using the testing framework
• test-sprocket-complete.sh - Complete test suite that starts relay and runs tests
• test-sprocket-manual.sh - Manual test script for interactive testing
• run-sprocket-test.sh - Automated test runner

Example Scripts

• test-sprocket-example.sh - Simple bash example sprocket script

Test Criteria

The Python sprocket script (test-sprocket.py) implements the following test criteria:

1. Spam Content: Rejects events containing "spam" in the content
2. Test Kind: Shadow rejects events with kind 9999
3. Blocked Hashtags: Rejects events with hashtags "blocked", "rejected", or "test-block"
4. Blocked Pubkeys: Shadow rejects events from pubkeys starting with "00000000", "11111111", or "22222222"
5. Content Length: Rejects events with content longer than 1000 characters
6. Timestamp Validation: Rejects events that are too old (>1 hour) or too far in the future (>5 minutes)

Running Tests

Quick Test (Recommended)

./test-sprocket-complete.sh

This script will:

1. Set up the test environment
2. Start the relay with sprocket enabled
3. Run all test cases
4. Clean up automatically

Manual Testing

# Start relay manually with sprocket enabled
export ORLY_SPROCKET_ENABLED=true
go run . test

# In another terminal, run manual tests
./test-sprocket-manual.sh

Integration Tests

# Run Go integration tests
go test -v -run TestSprocketIntegration ./test-sprocket-integration.go

Prerequisites

• Python 3: Required for the Python sprocket script
• jq: Required for JSON processing in bash scripts
• websocat: Required for WebSocket testing

  cargo install websocat
  

• Go dependencies: gorilla/websocket for integration tests

  go get github.com/gorilla/websocket
  

Test Cases

1. Normal Event (Accept)

{
  "id": "test_normal_123",
  "pubkey": "1234567890abcdef1234567890abcdef12345678",
  "created_at": 1640995200,
  "kind": 1,
  "content": "Hello, world!",
  "sig": "test_sig"
}

Expected: ["OK","test_normal_123",true]

2. Spam Content (Reject)

{
  "id": "test_spam_456",
  "pubkey": "1234567890abcdef1234567890abcdef12345678",
  "created_at": 1640995200,
  "kind": 1,
  "content": "This is spam content",
  "sig": "test_sig"
}

Expected: ["OK","test_spam_456",false,"error: Content contains spam"]

3. Test Kind (Shadow Reject)

{
  "id": "test_kind_789",
  "pubkey": "1234567890abcdef1234567890abcdef12345678",
  "created_at": 1640995200,
  "kind": 9999,
  "content": "Test message",
  "sig": "test_sig"
}

Expected: ["OK","test_kind_789",true] (but event not processed)

4. Blocked Hashtag (Reject)

{
  "id": "test_hashtag_101",
  "pubkey": "1234567890abcdef1234567890abcdef12345678",
  "created_at": 1640995200,
  "kind": 1,
  "content": "Message with hashtag",
  "tags": [["t", "blocked"]],
  "sig": "test_sig"
}

Expected: ["OK","test_hashtag_101",false,"error: Hashtag \"blocked\" is not allowed"]

5. Too Long Content (Reject)

{
  "id": "test_long_202",
  "pubkey": "1234567890abcdef1234567890abcdef12345678",
  "created_at": 1640995200,
  "kind": 1,
  "content": "a... (1001 characters)",
  "sig": "test_sig"
}

Expected: ["OK","test_long_202",false,"error: Content too long (max 1000 characters)"]

Sprocket Script Protocol

Input Format

Events are sent to the sprocket script as JSON objects via stdin, one per line.

Output Format

The sprocket script must respond with JSONL (JSON Lines) format:

{"id": "event_id", "action": "accept", "msg": ""}
{"id": "event_id", "action": "reject", "msg": "reason for rejection"}
{"id": "event_id", "action": "shadowReject", "msg": ""}

Actions

• accept: Continue with normal event processing
• reject: Return OK false to client with message
• shadowReject: Return OK true to client but abort processing

Configuration

To enable sprocket in the relay:

export ORLY_SPROCKET_ENABLED=true
export ORLY_APP_NAME="ORLY"

The sprocket script should be placed at: ~/.config/{ORLY_APP_NAME}/sprocket.sh

Troubleshooting

Common Issues

1. Sprocket script not found

   • Ensure the script exists at the correct path
   • Check file permissions (must be executable)

2. Python script errors

   • Verify Python 3 is installed
   • Check script syntax with python3 -m py_compile test-sprocket.py

3. WebSocket connection failed

   • Ensure relay is running on the correct port
   • Check firewall settings

4. Test failures

   • Check relay logs for sprocket errors
   • Verify sprocket script is responding correctly

Debug Mode

Enable debug logging:

export ORLY_LOG_LEVEL=debug

Manual Sprocket Testing

Test the sprocket script directly:

echo '{"id":"test","kind":1,"content":"spam test"}' | python3 test-sprocket.py

Expected output:

{"id": "test", "action": "reject", "msg": "Content contains spam"}

Contributing

When adding new test cases:

1. Add the test case to test-sprocket.py
2. Add corresponding test in test-sprocket-complete.sh
3. Update this README with the new test case
4. Ensure all tests pass before submitting

License

This test suite is part of the ORLY relay project and follows the same license.