Skip to content

Debugging River Integration

Jump to bottom
Ian Clarke edited this page Aug 27, 2025 · 1 revision

Debugging River Integration Issues

This page tracks ongoing debugging efforts for River chat integration with Freenet Core.

Primary Repositories Involved:

🔴 Current Status

Last Updated: 2025-08-27
Primary Issue: River end-to-end tests pass locally but fail with remote gateways
Confidence: High (reproducible)

📊 Test Matrix

Configuration Gateway Peers Result Last Tested Notes
Local 3-peer Local 3 local processes ✅ PASS 2025-08-26 Consistent success
Remote AWS AWS EC2 2 local → remote ❌ FAIL 2025-08-26 Subscription timeout
Remote Nova nova.locut.us 2 local → remote ❌ FAIL 2025-08-26 Similar to AWS

🔬 Active Hypotheses

H1: Network/Gateway Communication Issue

Status: 🟡 PRIMARY INVESTIGATION
Confidence: 75%

Evidence FOR:

  • Local tests pass consistently
  • Remote tests fail consistently
  • Failure point: subscription/connection establishment
  • Pattern holds across different cloud providers

Evidence AGAINST:

  • Ping app works fine with remote gateways
  • Basic PUT/GET operations succeed

Test Plan:

  1. Test with peers on different physical machines (local network)
  2. Test with peers on completely different networks
  3. Monitor network traffic during failure

H2: WebSocket API Client-Peer Communication

Status: 🟡 INVESTIGATING
Confidence: 40%

Evidence FOR:

  • Multiple subscriptions on same peer may be problematic
  • Not well tested scenario
  • Nacho expressed concerns about current implementation

Evidence AGAINST:

  • Single subscription scenarios also fail

Test Plan:

  • Isolate to single user per peer
  • Review WebSocket message flow

✅ Resolved Issues

Subscribe Flag with GET Requests

Resolution: Now using separate subscribe messages
Date Resolved: 2025-08-26
Fix: River v0.1.x release updated to separate GET and SUBSCRIBE operations

UDP Issues with AWS

Resolution: Workaround - use alternative provider/port
Date Resolved: 2025-08-25
Notes: Port 31337 potentially problematic (known backdoor port)

🧪 Experiments

Experiment 001: Local vs Remote Gateway

Date: 2025-08-26
Test: River multi-user end-to-end test
Variables: Gateway location only

# Local test (PASSES)
cd ~/code/freenet/freenet-testing-tools/gateway-testing
python gateway_test_framework.py --local

# Remote test (FAILS)
python gateway_test_framework.py --remote-gateway nova.locut.us

Results:

  • Local: Room creation → invite → join → message exchange all work
  • Remote: Fails at subscription establishment after room creation

Experiment 002: Peer Isolation Levels

Date: 2025-08-27 (PLANNED)
Test: Progressive isolation of peers
Variables: Process isolation, machine isolation, network isolation

Test Matrix:

  1. Same peer, multiple River instances (NOT RECOMMENDED)
  2. Different processes, same machine, same network
  3. Different machines, same network
  4. Different machines, different networks

📝 Code Investigation Notes

Key Code Areas

  • crates/core/src/operations/subscribe.rs:712 - Subscription handling
  • crates/core/src/operations/update.rs - Update propagation
  • WebSocket API gateway connection establishment
  • River contract initial setup flow

Suspicious Patterns

  1. Timing-dependent operations in remote scenarios
  2. Potential race conditions in invitation acceptance
  3. Gateway-peer connection state management

🔧 Known Workarounds

Issue Workaround Status
AWS UDP issues Use non-AWS provider ✅ Active
Port 31337 issues Use alternative port ✅ Active
Multiple users per peer One peer per user ✅ Active
Subscribe with GET Separate operations ✅ Implemented

📋 Action Items

Ian

  • Confirm local success is reproducible (3+ runs)
  • Test with different peer isolation levels
  • Document exact test configurations
  • Provide SSH access to nova.locut.us for team

Nacho/Hector

  • Review gateway test framework code
  • Port test logic to integration test suite
  • Attempt local reproduction of issue
  • Review River PR integration tests

🔗 Related Resources

📜 Log Snippets

Typical Remote Failure

2025-08-26 23:45:12 ERROR subscription timeout after 30s
2025-08-26 23:45:12 ERROR room_id: 6P5SgHxio9cEF5Cn1ZHb8F7kt88g2skhgTNjCJyD4f3Q
2025-08-26 23:45:12 ERROR peer: local → gateway: nova.locut.us

Successful Local Run

2025-08-26 23:30:45 INFO room created successfully
2025-08-26 23:30:46 INFO invitation sent
2025-08-26 23:30:47 INFO peer joined room
2025-08-26 23:30:48 INFO message exchange successful
Clone this wiki locally