Metadata-Version: 2.4
Name: retunnel
Version: 2.5.2
Summary: ReTunnel - Securely expose local servers to the internet
Author-email: ReTunnel Team <support@retunnel.com>
License-Expression: MIT
Keywords: tunnel,ngrok,localhost,webhook,http,https,tcp,reverse-proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: websockets>=11.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiofiles>=24.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: bandit>=1.8.3; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: aioresponses>=0.7.4; extra == "dev"
Requires-Dist: types-aiofiles; extra == "dev"
Requires-Dist: types-pyyaml; extra == "dev"
Dynamic: license-file

# ReTunnel Client

[![PyPI Version](https://badge.fury.io/py/retunnel.svg)](https://pypi.org/project/retunnel/)
[![Python Versions](https://img.shields.io/pypi/pyversions/retunnel.svg)](https://pypi.org/project/retunnel/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

ReTunnel is a secure tunnel service that allows you to expose local servers to the internet. This is the official Python client library and CLI.

## Features

- 🚀 **Easy to use** - Single command to expose your local server
- 🔒 **Secure** - All connections are encrypted
- 🌐 **HTTP/HTTPS and TCP** - Support for web and TCP services
- 🔑 **Automatic registration** - No sign-up required for basic usage
- ⚡ **High performance** - Built with asyncio for efficiency
- 🎛️ **Professional CLI** - Rich terminal interface with Typer

## Installation

```bash
pip install retunnel
```

Requires Python 3.9 or higher.

## Quick Start

### HTTP Tunnel

Expose a local web server on port 8080:

```bash
retunnel http 8080
```

### TCP Tunnel

Expose a local TCP service on port 22:

```bash
retunnel tcp 22
```

### With Custom Subdomain

Request a specific subdomain (subject to availability):

```bash
retunnel http 8080 --subdomain myapp
```

### With Authentication

Protect your tunnel with HTTP Basic Auth:

```bash
retunnel http 8080 --auth user:password
```

## Configuration

### Server Endpoint

By default, ReTunnel connects to `localhost:6400`. You can configure this using:

- Environment variable: `RETUNNEL_SERVER_ENDPOINT=your.server.com:port`
- Command-line option: `--server your.server.com:port`
- Configuration file: `server_addr: your.server.com:port`

### Save Authentication Token

Save your auth token for persistent access:

```bash
retunnel authtoken YOUR_AUTH_TOKEN
```

### Configuration File

Create a `retunnel.yml` file to define multiple tunnels:

```yaml
server_addr: ${RETUNNEL_SERVER_ENDPOINT:localhost:6400}
auth_token: ${RETUNNEL_AUTH_TOKEN}
log_level: INFO

tunnels:
  - name: web
    protocol: http
    local_port: 8080
    subdomain: myapp
    
  - name: api
    protocol: http
    local_port: 3000
    auth: user:pass
    
  - name: ssh
    protocol: tcp
    local_port: 22
```

Then start all tunnels:

```bash
retunnel start retunnel.yml
```

## Environment Variables

- `RETUNNEL_SERVER_ENDPOINT` - Server endpoint (default: `localhost:6400`)
- `RETUNNEL_AUTH_TOKEN` - Authentication token
- `RETUNNEL_LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR)

## Python API

```python
import asyncio
from retunnel import ReTunnelClient, TunnelConfig

async def main():
    # Create client
    client = ReTunnelClient()
    
    # Connect to server
    await client.connect()
    
    # Create HTTP tunnel
    config = TunnelConfig(protocol="http", local_port=8080)
    tunnel = await client.request_tunnel(config)
    
    print(f"Tunnel URL: {tunnel.url}")
    
    # Keep running
    await asyncio.Event().wait()

asyncio.run(main())
```

## Advanced Usage

### Custom Server

Connect to a self-hosted ReTunnel server:

```bash
retunnel http 8080 --server your-server.com:8000
```

### Multiple Tunnels

Use the configuration file to manage multiple tunnels simultaneously.

### Logging

Set log level for debugging:

```bash
retunnel http 8080 --log-level DEBUG
```

## CLI Commands

- `retunnel http PORT` - Create HTTP tunnel
- `retunnel tcp PORT` - Create TCP tunnel
- `retunnel start CONFIG` - Start tunnels from config file
- `retunnel authtoken TOKEN` - Save authentication token
- `retunnel config` - Manage configuration
- `retunnel version` - Show version
- `retunnel credits` - Show open source credits

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/retunnel/retunnel-client
cd retunnel-client

# Install with development dependencies
make install-dev
```

### Testing

```bash
# Run tests
make test

# Run linting
make lint

# Run type checking
make typecheck

# Format code
make format
```

### Building

```bash
make build
```

## License

MIT License - see LICENSE file for details.

## Credits

ReTunnel uses these excellent open source libraries:

- aiohttp - Async HTTP client/server
- websockets - WebSocket client/server
- msgpack - Efficient serialization
- typer - CLI framework
- rich - Terminal formatting
- pydantic - Data validation

## Support

- Documentation: https://docs.retunnel.com
- Issues: https://github.com/retunnel/retunnel-client/issues
- Email: support@retunnel.com
