🔨 Add some tests utilities of activity pub
This commit is contained in:
448
docs/ACTIVITYPUB_TESTING_INDEX.md
Normal file
448
docs/ACTIVITYPUB_TESTING_INDEX.md
Normal file
@@ -0,0 +1,448 @@
|
||||
# ActivityPub Testing - Complete Guide
|
||||
|
||||
This is the complete guide for testing ActivityPub federation in Solar Network.
|
||||
|
||||
## 📁 File Overview
|
||||
|
||||
| File | Purpose | When to Use |
|
||||
|------|---------|--------------|
|
||||
| `setup-activitypub-test.sh` | One-command setup of test environment | First time setup |
|
||||
| `test-activitypub.sh` | Quick validation of basic functionality | After setup, before detailed tests |
|
||||
| `ACTIVITYPUB_TESTING_QUICKSTART.md` | Quick start reference | Getting started quickly |
|
||||
| `ACTIVITYPUB_TESTING_GUIDE.md` | Comprehensive testing scenarios | Full testing workflow |
|
||||
| `ACTIVITYPUB_TESTING_QUICKREF.md` | Command and query reference | Daily testing |
|
||||
| `ACTIVITYPUB_TESTING_HELPER_API.md` | Helper API for testing | Programmatic testing |
|
||||
| `ACTIVITYPUB_TEST_RESULTS_TEMPLATE.md` | Track test results | During testing |
|
||||
| `ACTIVITYPUB_IMPLEMENTATION.md` | Implementation details | Understanding the code |
|
||||
| `ACTIVITYPUB_SUMMARY.md` | Feature summary | Reviewing what's implemented |
|
||||
|
||||
## 🚀 Quick Start (5 Minutes)
|
||||
|
||||
### 1. Setup Test Environment
|
||||
|
||||
```bash
|
||||
./setup-activitypub-test.sh
|
||||
```
|
||||
|
||||
This will:
|
||||
- ✅ Configure `/etc/hosts`
|
||||
- ✅ Start Mastodon via Docker
|
||||
- ✅ Create test Mastodon account
|
||||
- ✅ Apply database migrations
|
||||
|
||||
### 2. Validate Setup
|
||||
|
||||
```bash
|
||||
./test-activitypub.sh
|
||||
```
|
||||
|
||||
This checks:
|
||||
- ✅ WebFinger endpoint
|
||||
- ✅ Actor profile
|
||||
- ✅ Public keys
|
||||
- ✅ Database tables
|
||||
|
||||
### 3. Start Solar Network
|
||||
|
||||
```bash
|
||||
cd DysonNetwork.Sphere
|
||||
dotnet run
|
||||
```
|
||||
|
||||
### 4. Test Federation
|
||||
|
||||
1. Open http://mastodon.local:3001
|
||||
2. Search for `@solaruser@solar.local`
|
||||
3. Click Follow
|
||||
4. Create a post in Solar Network
|
||||
5. Verify it appears in Mastodon
|
||||
|
||||
## 📖 Recommended Reading Order
|
||||
|
||||
### For First-Time Testing
|
||||
|
||||
1. **Start Here**: `ACTIVITYPUB_TESTING_QUICKSTART.md`
|
||||
- Overview of the setup
|
||||
- Quick command reference
|
||||
- Common commands
|
||||
|
||||
2. **Then**: `ACTIVITYPUB_TESTING_GUIDE.md`
|
||||
- Detailed test scenarios
|
||||
- Step-by-step instructions
|
||||
- Troubleshooting
|
||||
|
||||
3. **Reference**: `ACTIVITYPUB_TESTING_QUICKREF.md`
|
||||
- Command snippets
|
||||
- Database queries
|
||||
- Response codes
|
||||
|
||||
### During Testing
|
||||
|
||||
1. **Track Progress**: `ACTIVITYPUB_TEST_RESULTS_TEMPLATE.md`
|
||||
- Checklists for each test
|
||||
- Results tracking
|
||||
- Issue logging
|
||||
|
||||
2. **Helper API**: `ACTIVITYPUB_TESTING_HELPER_API.md`
|
||||
- Manual testing endpoints
|
||||
- Debugging tools
|
||||
- Status monitoring
|
||||
|
||||
### For Understanding
|
||||
|
||||
1. **Implementation**: `ACTIVITYPUB_IMPLEMENTATION.md`
|
||||
- Architecture details
|
||||
- Service descriptions
|
||||
- Data flow diagrams
|
||||
|
||||
2. **Features**: `ACTIVITYPUB_SUMMARY.md`
|
||||
- What's implemented
|
||||
- Model relationships
|
||||
- API endpoints
|
||||
|
||||
## 🔍 Test Scenarios Summary
|
||||
|
||||
### Basic Functionality (All instances must pass)
|
||||
|
||||
- [ ] WebFinger discovery works
|
||||
- [ ] Actor profile is valid JSON-LD
|
||||
- [ ] Public key is present
|
||||
- [ ] Outbox returns public posts
|
||||
- [ ] Inbox accepts activities
|
||||
|
||||
### Federation - Follow
|
||||
|
||||
- [ ] Remote user can follow local user
|
||||
- [ ] Local user can follow remote user
|
||||
- [ ] Accept activity is sent/received
|
||||
- [ ] Relationship state is correct
|
||||
- [ ] Unfollow works correctly
|
||||
|
||||
### Federation - Content
|
||||
|
||||
- [ ] Local posts federate to remote instances
|
||||
- [ ] Remote posts appear in local database
|
||||
- [ ] Post content is preserved
|
||||
- [ ] Timestamps are correct
|
||||
- [ ] Attachments are handled
|
||||
- [ ] Content warnings are respected
|
||||
|
||||
### Federation - Interactions
|
||||
|
||||
- [ ] Likes federate correctly
|
||||
- [ ] Likes appear in both instances
|
||||
- [ ] Replies federate correctly
|
||||
- [ ] Reply threading works
|
||||
- [ ] Boosts/Announces work
|
||||
- [ ] Undo activities work
|
||||
|
||||
### Security
|
||||
|
||||
- [ ] HTTP signatures are verified
|
||||
- [ ] Invalid signatures are rejected
|
||||
- [ ] Keys are properly stored
|
||||
- [ ] Private keys never exposed
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### Issue: "Failed to verify signature"
|
||||
|
||||
**Causes**:
|
||||
1. Signature header format is wrong
|
||||
2. Public key doesn't match keyId
|
||||
3. Date header is too old (>5 minutes)
|
||||
4. Request body doesn't match digest
|
||||
|
||||
**Solutions**:
|
||||
1. Check signature format: `keyId="...",algorithm="...",headers="...",signature="..."`
|
||||
2. Verify keyId in actor profile
|
||||
3. Ensure Date header is recent
|
||||
4. Check body is exactly what was signed
|
||||
|
||||
### Issue: "Target actor or inbox not found"
|
||||
|
||||
**Causes**:
|
||||
1. Actor hasn't been fetched yet
|
||||
2. Actor URL is incorrect
|
||||
3. Remote instance is inaccessible
|
||||
|
||||
**Solutions**:
|
||||
1. Manually fetch actor first
|
||||
2. Verify actor URL is correct
|
||||
3. Test accessibility with curl
|
||||
|
||||
### Issue: Activities not arriving
|
||||
|
||||
**Causes**:
|
||||
1. Network connectivity issue
|
||||
2. Remote instance is down
|
||||
3. Activity wasn't queued properly
|
||||
|
||||
**Solutions**:
|
||||
1. Check network connectivity
|
||||
2. Verify remote instance is running
|
||||
3. Check fediverse_activities table for status
|
||||
|
||||
## 📊 Monitoring During Tests
|
||||
|
||||
### Check Logs
|
||||
|
||||
```bash
|
||||
# Solar Network ActivityPub logs
|
||||
dotnet run --project DysonNetwork.Sphere 2>&1 | grep -i activitypub
|
||||
|
||||
# Mastodon federation logs
|
||||
docker compose -f docker-compose.mastodon-test.yml logs -f web | grep -i federation
|
||||
```
|
||||
|
||||
### Monitor Database
|
||||
|
||||
```bash
|
||||
# Watch activity table
|
||||
watch -n 2 'psql -d dyson_network -c \
|
||||
"SELECT type, status, created_at FROM fediverse_activities ORDER BY created_at DESC LIMIT 5;"'
|
||||
```
|
||||
|
||||
### Test Network
|
||||
|
||||
```bash
|
||||
# Test connectivity between instances
|
||||
curl -v http://mastodon.local:3001
|
||||
curl -v http://solar.local:5000
|
||||
|
||||
# Test with traceroute (if available)
|
||||
traceroute mastodon.local
|
||||
traceroute solar.local
|
||||
```
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Minimal Viable Federation
|
||||
|
||||
To consider ActivityPub implementation "working", all of these must pass:
|
||||
|
||||
- ✅ WebFinger returns actor links
|
||||
- ✅ Actor profile has all required fields
|
||||
- ✅ Follow relationships work bidirectionally
|
||||
- ✅ Public posts federate to followers
|
||||
- ✅ Incoming posts are stored correctly
|
||||
- ✅ HTTP signatures are verified
|
||||
- ✅ Basic interaction types work (Like, Reply)
|
||||
|
||||
### Full Production Ready
|
||||
|
||||
For production, also need:
|
||||
|
||||
- ✅ Activity queue with retry logic
|
||||
- ✅ Rate limiting on outgoing deliveries
|
||||
- ✅ Monitoring and alerting
|
||||
- ✅ Admin interface for federation management
|
||||
- ✅ Content filtering and moderation
|
||||
- ✅ Instance blocking capabilities
|
||||
- ✅ Performance optimization for high volume
|
||||
|
||||
## 🔐 Security Checklist
|
||||
|
||||
During testing, verify:
|
||||
|
||||
- [ ] Private keys are never logged
|
||||
- [ ] Private keys are never returned in API responses
|
||||
- [ ] Only public keys are in actor profiles
|
||||
- [ ] All incoming activities are signature-verified
|
||||
- [ ] Invalid signatures are rejected with 401
|
||||
- [ ] TLS is used in production
|
||||
- [ ] Host header is verified against request URL
|
||||
|
||||
## 📈 Performance Metrics
|
||||
|
||||
Track these during testing:
|
||||
|
||||
| Metric | Target | Actual |
|
||||
|--------|--------|--------|
|
||||
| WebFinger response time | <500ms | ___ ms |
|
||||
| Actor fetch time | <1s | ___ ms |
|
||||
| Signature verification time | <100ms | ___ ms |
|
||||
| Activity processing time | <500ms | ___ ms |
|
||||
| Outgoing delivery success rate | >95% | ___% |
|
||||
| Outgoing delivery time | <5s | ___ ms |
|
||||
|
||||
## 🧪 Testing Checklist
|
||||
|
||||
### Self-Hosted Instance Tests
|
||||
|
||||
**Setup**:
|
||||
- [ ] Setup script completed
|
||||
- [ ] Mast containers running
|
||||
- [ ] Solar Network running
|
||||
- [ ] /etc/hosts configured
|
||||
- [ ] Database migrations applied
|
||||
|
||||
**Basic Federation**:
|
||||
- [ ] WebFinger works
|
||||
- [ ] Actor profile valid
|
||||
- [ ] Public key present
|
||||
- [ ] Outbox accessible
|
||||
|
||||
**Follow Flow**:
|
||||
- [ ] Mastodon → Solar follow works
|
||||
- [ ] Solar → Mastodon follow works
|
||||
- [ ] Accept activity sent
|
||||
- [ ] Relationship state correct
|
||||
|
||||
**Content Flow**:
|
||||
- [ ] Solar posts appear in Mastodon
|
||||
- [ ] Mastodon posts appear in Solar
|
||||
- [ ] Content preserved correctly
|
||||
- [ ] Timestamps correct
|
||||
|
||||
**Interactions**:
|
||||
- [ ] Likes work both ways
|
||||
- [ ] Replies work both ways
|
||||
- [ ] Boosts work both ways
|
||||
- [ ] Undo works
|
||||
|
||||
**Security**:
|
||||
- [ ] HTTP signatures verified
|
||||
- [ ] Invalid signatures rejected
|
||||
- [ ] Keys properly managed
|
||||
|
||||
### Real Instance Tests
|
||||
|
||||
**Discovery**:
|
||||
- [ ] Domain publicly accessible
|
||||
- [ ] WebFinger works from public internet
|
||||
- [ ] Actor discoverable from public instances
|
||||
|
||||
**Federation**:
|
||||
- [ ] Posts federate to public instances
|
||||
- [ ] Follows work with public instances
|
||||
- [ ] Interactions work with public instances
|
||||
|
||||
## 📝 Testing Notes
|
||||
|
||||
### What Worked Well
|
||||
1. _____________________
|
||||
2. _____________________
|
||||
3. _____________________
|
||||
|
||||
### What Needs Improvement
|
||||
1. _____________________
|
||||
2. _____________________
|
||||
3. _____________________
|
||||
|
||||
### Bugs Found
|
||||
| # | Description | Severity | Status |
|
||||
|---|-------------|----------|--------|
|
||||
| 1 | _____________________ | Low/Medium/High | ☐ Open/☐ Fixed |
|
||||
| 2 | _____________________ | Low/Medium/High | ☐ Open/☐ Fixed |
|
||||
| 3 | _____________________ | Low/Medium/High | ☐ Open/☐ Fixed |
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### ActivityPub Specification
|
||||
- [W3C ActivityPub Recommendation](https://www.w3.org/TR/activitypub/)
|
||||
- [ActivityStreams 2.0](https://www.w3.org/TR/activitystreams-core/)
|
||||
- [HTTP Signatures Draft](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
|
||||
|
||||
### Implementation Guides
|
||||
- [Mastodon Federation Guide](https://docs.joinmastodon.org/admin/federation/)
|
||||
- [ActivityPub Testing Best Practices](https://blog.joinmastodon.org/2018/06/27/how-to-implement-a-basic-activitypub-server/)
|
||||
- [Federation Testing Checklist](https://docs.joinmastodon.org/spec/activitypub/)
|
||||
|
||||
### Tools
|
||||
- [ActivityPub Playground](https://swicth.github.io/activity-pub-playground/)
|
||||
- [FediTest](https://feditest.com/)
|
||||
- [JSONPath Online Evaluator](https://jsonpath.com/)
|
||||
|
||||
## 🔄 Next Steps After Testing
|
||||
|
||||
### Phase 1: Fix Issues
|
||||
- Address all bugs found during testing
|
||||
- Improve error messages
|
||||
- Add better logging
|
||||
|
||||
### Phase 2: Enhance Features
|
||||
- Implement activity queue
|
||||
- Add retry logic
|
||||
- Add rate limiting
|
||||
- Implement instance blocking
|
||||
|
||||
### Phase 3: Production Readiness
|
||||
- Add monitoring and metrics
|
||||
- Add admin interface
|
||||
- Add content filtering
|
||||
- Implement moderation tools
|
||||
|
||||
### Phase 4: Additional Features
|
||||
- Support more activity types
|
||||
- Support media attachments
|
||||
- Support polls
|
||||
- Support custom emojis
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. **Check logs**: See the logs section above
|
||||
2. **Review troubleshooting**: See `ACTIVITYPUB_TESTING_GUIDE.md` Part 5
|
||||
3. **Check database queries**: Use queries from `ACTIVITYPUB_TESTING_QUICKREF.md`
|
||||
4. **Validate signatures**: Use helper API in `ACTIVITYPUB_TESTING_HELPER_API.md`
|
||||
|
||||
## ✨ Quick Test Commands
|
||||
|
||||
### All-in-One Test Sequence
|
||||
|
||||
```bash
|
||||
# 1. Setup
|
||||
./setup-activitypub-test.sh
|
||||
|
||||
# 2. Validate
|
||||
./test-activitypub.sh
|
||||
|
||||
# 3. Test WebFinger
|
||||
curl "http://solar.local:5000/.well-known/webfinger?resource=acct:solaruser@solar.local"
|
||||
|
||||
# 4. Test Actor
|
||||
curl -H "Accept: application/activity+json" \
|
||||
http://solar.local:5000/activitypub/actors/solaruser
|
||||
|
||||
# 5. Test Follow (from Mastodon UI)
|
||||
# Open http://mastodon.local:3001 and follow @solaruser@solar.local
|
||||
|
||||
# 6. Check database
|
||||
psql -d dyson_network -c "SELECT * FROM fediverse_relationships;"
|
||||
|
||||
# 7. Test Post (create in Solar Network UI)
|
||||
# Should appear in http://mastodon.local:3001
|
||||
|
||||
# 8. Verify content
|
||||
psql -d dyson_network -c "SELECT * FROM fediverse_contents;"
|
||||
|
||||
# 9. Test Like (like from Mastodon UI)
|
||||
# Should appear in fediverse_reactions table
|
||||
|
||||
# 10. Check activities
|
||||
psql -d dyson_network -c "SELECT type, status FROM fediverse_activities;"
|
||||
```
|
||||
|
||||
## 🎉 Conclusion
|
||||
|
||||
You now have everything needed to test ActivityPub federation for Solar Network:
|
||||
|
||||
- ✅ Self-hosted test environment (Mastodon)
|
||||
- ✅ Setup automation (setup script)
|
||||
- ✅ Quick validation (test script)
|
||||
- ✅ Comprehensive testing guide
|
||||
- ✅ Helper API for programmatic testing
|
||||
- ✅ Quick reference for daily use
|
||||
- ✅ Results template for tracking progress
|
||||
|
||||
**Recommended workflow**:
|
||||
1. Run `setup-activitypub-test.sh`
|
||||
2. Run `test-activitypub.sh` for validation
|
||||
3. Follow scenarios in `ACTIVITYPUB_TESTING_GUIDE.md`
|
||||
4. Use `ACTIVITYPUB_TESTING_HELPER_API.md` for specific tests
|
||||
5. Track results in `ACTIVITYPUB_TEST_RESULTS_TEMPLATE.md`
|
||||
6. Reference `ACTIVITYPUB_TESTING_QUICKREF.md` for commands
|
||||
|
||||
Good luck with your federation testing! 🚀
|
||||
Reference in New Issue
Block a user