Skip to content

README.md

Latest commit

 

History

History
253 lines (188 loc) · 5.98 KB

README.md

File metadata and controls

253 lines (188 loc) · 5.98 KB

mesh-router-backend Development Environment

Docker-based development environment for mesh-router-backend with hot reload and integrated testing.

Quick Start

Prerequisites

  • Docker and Docker Compose
  • Firebase service account JSON file

Setup

  1. Add Firebase credentials:

    # Copy your service account to the config directory
cp /path/to/your/serviceAccount.json ../config/serviceAccount.json

  2. Configure environment:

    # Copy the example env file
cp .env.example .env

# Edit .env and set your server domain
# SERVER_DOMAIN=nsl.sh

  3. Start the development server:

    # Linux/Mac
./start.sh

# Windows PowerShell
.\start.ps1

  4. Access the API:

    http://localhost:8192

Scripts

Script Description
start.sh / start.ps1 Start dev environment with logs
stop.sh / stop.ps1 Stop containers (use --clean to remove volumes)
test.sh / test.ps1 Run the test suite

Running Tests

# Linux/Mac
./test.sh

# Windows PowerShell
.\test.ps1

# Or manually
docker compose up -d
docker compose exec mesh-router-backend pnpm test

Test Output

IP Registration API
  POST /ip/:userid/:sig
    ✔ should register Host IP with valid signature
    ✔ should reject invalid signature
    ✔ should reject missing hostIp in body
    ✔ should reject invalid IP format
    ✔ should reject non-existent user
    ✔ should accept valid IPv6 address
    ✔ should update existing IP with new value
  GET /resolve/:domain
    ✔ should resolve domain to IP
    ✔ should return 404 for unknown domain
    ✔ should return 404 for domain without IP registered
    ✔ should handle case-insensitive domain lookup

11 passing

Architecture

backend-dev/
├── Dockerfile.dev        # Node 22 Alpine + pnpm (thin image)
├── docker-compose.yml    # Service definition with volume mounts
├── entrypoint-dev.sh     # Smart startup script
├── start.sh / start.ps1  # Start dev environment
├── stop.sh / stop.ps1    # Stop dev environment
├── test.sh / test.ps1    # Run tests
├── .env.example          # Environment template
├── .gitignore            # Excludes secrets
└── README.md             # This file

Docker Compose Configuration

Volumes

Volume Purpose
..:/app Source code (hot reload)
node_modules Named volume for dependencies (performance)
pnpm-store pnpm cache (faster installs)
../config:/app/config Firebase service account

Environment Variables

Variable Description Default
SERVER_DOMAIN Server domain suffix for all user domains (e.g., nsl.sh) Required
NODE_ENV Node environment development
GOOGLE_APPLICATION_CREDENTIALS Path to Firebase service account /app/config/serviceAccount.json

Create a .env file from the example:

cp .env.example .env
# Edit .env and set SERVER_DOMAIN=your-domain.com

Development Workflow

Hot Reload

The dev server uses tsc-watch for automatic TypeScript compilation and restart on file changes:

  1. Edit any .ts file in src/
  2. Save the file
  3. TypeScript recompiles automatically
  4. Server restarts with new code

Viewing Logs

# Follow logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail 100

Shell Access

docker compose exec mesh-router-backend bash

Manual Commands Inside Container

# Install dependencies
pnpm install

# Build only
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

API Endpoints

Domain Management

Method Endpoint Auth Description
GET /available/:domain Public Check domain availability
GET /domain/:userid Public Get user's domain info
POST /domain Firebase Register/update domain
DELETE /domain Firebase Delete domain
GET /verify/:userid/:sig Public Verify domain ownership

Routes v2 API (Redis-backed)

Method Endpoint Auth Description
POST /routes/:userid/:sig Ed25519 Signature Register routes for a user
GET /routes/:userid Public Get routes for a user
DELETE /routes/:userid/:sig Ed25519 Signature Delete routes for a user
GET /resolve/v2/:domain Public Resolve domain to routes

Example Usage

# Check domain availability
curl http://localhost:8192/available/myname

# Resolve domain to routes (v2 API)
curl http://localhost:8192/resolve/v2/myname
# Response: {"userId":"abc123","domainName":"myname","serverDomain":"<SERVER_DOMAIN>","routes":[{"ip":"10.77.0.5","port":443,"priority":1}],"routesTtl":580}

# Register routes (requires signature)
curl -X POST http://localhost:8192/routes/{userid}/{signature} \
  -H "Content-Type: application/json" \
  -d '{"routes": [{"ip": "10.77.0.5", "port": 443, "priority": 1}]}'
# Response: {"message":"Routes registered successfully.","routes":[...],"domain":"myname.<SERVER_DOMAIN>"}

Note: serverDomain in responses comes from the SERVER_DOMAIN environment variable.

Troubleshooting

Container won't start

  1. Check if port 8192 is in use:

    lsof -i :8192  # Linux/Mac
netstat -ano | findstr 8192  # Windows

  2. Check Docker logs:

    docker compose logs

Firebase errors

  1. Ensure serviceAccount.json exists in ../config/
  2. Check the file is valid JSON
  3. Verify the service account has Firestore access

Dependencies not installing

# Clean and reinstall
./stop.sh --clean
./start.sh

TypeScript errors

# Check compilation manually
docker compose exec mesh-router-backend pnpm build

Cleanup

# Stop containers, keep volumes (node_modules preserved)
./stop.sh

# Full cleanup (removes node_modules volume)
./stop.sh --clean