449 lines
12 KiB
Markdown
449 lines
12 KiB
Markdown
# 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! 🚀
|