Laravel Tunnelhunt Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tunnelhunt/laravel-tunnelhunt
   

   No manual service provider registration needed (auto-discovered).

2. First Use Case: Test webhooks (e.g., Telegram, Stripe) or share a live demo without deploying. Run:

   php artisan serve:tunnel
   

   • Outputs local server URL (http://127.0.0.1:8000) and public tunnel URL (e.g., http://a1b2c3d4.tunnelhunt.ru).
   • Key Action: Copy the public URL to share or configure external services.

3. Where to Look First:

   • Command Help: php artisan serve:tunnel --help for options.
   • SSH Output: Monitor tunnel status in the terminal (e.g., connection logs, URL updates).

Implementation Patterns

Workflows

1. Local Development + Public Access:

   • Pattern: Use serve:tunnel during feature development requiring external API calls (e.g., payment gateways).
   • Example:

     php artisan serve:tunnel --port=8080 --plan=pro
     

     • Runs Laravel server on 8080 with a pro plan tunnel.
     • Share http://<random>.tunnelhunt.ru with stakeholders for testing.

2. CI/CD Integration:

   • Pattern: Trigger tunnel creation in deployment pipelines (e.g., GitHub Actions) for pre-production testing.
   • Example Workflow:

     # .github/workflows/test.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - run: php artisan serve:tunnel --port=8000 &
           - run: sleep 30  # Wait for tunnel to stabilize
           - run: curl http://$(php artisan serve:tunnel --url)  # Fetch public URL
     

3. Environment-Specific Config:

   • Pattern: Override defaults via .env (not natively supported; use custom config):

     // config/tunnelhunt.php
     return [
         'default_port' => env('TUNNELHUNT_PORT', 8000),
         'default_plan' => env('TUNNELHUNT_PLAN', 'nokey'),
     ];
     

   • Usage:

     php artisan serve:tunnel --port=$TUNNELHUNT_PORT
     

Integration Tips

• Webhook Testing:

  • Configure external services (e.g., Telegram bots) to send webhooks to the public tunnel URL.
  • Debugging: Use Laravel’s Log::info() to verify incoming requests in routes/web.php:

    Route::post('/webhook', function () {
        Log::info('Webhook received', ['data' => request()->all()]);
    });
    

• HTTPS:

  • TunnelHunt provides HTTPS by default. For local testing, use:

    php artisan serve:tunnel --port=8000 --host=0.0.0.0
    

    Then access via https://<tunnel-url>.

• Long-Running Processes:

  • Use nohup or screen to keep the tunnel alive after closing the terminal:

    nohup php artisan serve:tunnel --port=8000 > tunnel.log 2>&1 &
    

Gotchas and Tips

Pitfalls

1. SSH Dependencies:

   • Error: ssh: command not found.
   • Fix: Ensure SSH is installed and in PATH. On macOS/Linux:

     which ssh  # Should return /usr/bin/ssh
     

   • On Windows, use Git Bash or WSL.

2. Port Conflicts:

   • Error: Address already in use if port 8000 is occupied.
   • Fix: Specify a free port:

     php artisan serve:tunnel --port=8080
     

3. Tunnel Stability:

   • Issue: nokey plan tunnels may drop after inactivity.
   • Fix: Use --plan=pro for persistent tunnels or ping the endpoint periodically:

     watch -n 5 "curl -s http://$(php artisan serve:tunnel --url)"
     

4. Firewall/Network Restrictions:

   • Issue: Tunnel fails to connect due to corporate firewalls.
   • Fix: Use a VPN or whitelist tunnelhunt.ru (port 2222).

Debugging

• SSH Verbose Mode: Enable debug logs to troubleshoot connection issues:

  php artisan serve:tunnel --debug
  

  • Look for errors like Connection refused or Permission denied.

• Public URL Extraction: If the URL isn’t auto-detected, parse SSH output manually:

  php artisan serve:tunnel 2>&1 | grep "Your public URL is"
  

Config Quirks

1. Plan Limitations:

   • nokey: Free but less reliable (random URLs, no persistence).
   • pro: Requires a paid TunnelHunt account (contact support for credentials).

2. Host Binding:

   • Binding to 0.0.0.0 exposes the server to LAN. Use cautiously:

     php artisan serve:tunnel --host=0.0.0.0
     

Extension Points

1. Custom SSH Commands: Override the SSH command in the service provider (app/Providers/TunnelHuntServiceProvider.php):

   protected function getSshCommand(): string
   {
       return 'ssh -R 80:localhost:'.$this->port.' -p 2222 custom@tunnelhunt.ru';
   }
   

2. Post-Tunnel Hooks: Extend the command to run tasks after tunnel creation (e.g., update .env):

   // app/Console/Commands/ServeTunnel.php
   protected function handle()
   {
       $url = $this->getPublicUrl();
       file_put_contents('.env', "TUNNEL_URL={$url}\n", FILE_APPEND);
   }
   

3. URL Validation: Add validation to ensure the tunnel URL is reachable:

   public function isUrlReachable(string $url): bool
   {
       $ch = curl_init($url);
       curl_setopt($ch, CURLOPT_NOBODY, true);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
       curl_setopt($ch, CURLOPT_TIMEOUT, 5);
       return curl_errno($ch) === 0;
   }