hightower-client 0.1.5

# Hightower Client Library

A Rust library for building applications that connect to Hightower gateways with integrated WireGuard transport.

## Overview

This library provides a complete solution for connecting to Hightower gateways. It handles everything internally:

- WireGuard transport creation and management
- Certificate/keypair generation
- Network discovery via STUN using actual bound ports
- Gateway registration
- Peer configuration
- Automatic deregistration on disconnect
- **Connection persistence and automatic restoration**

**You only provide:** gateway URL and auth token
**You get:** a working transport, node ID, and assigned IP

Everything else is handled automatically!

### Connection Persistence (New in 0.1.1)

By default, connections are automatically persisted to `~/.hightower/gateway/<gateway>/`. When you reconnect to the same gateway:
- The library reuses your stored WireGuard keys (same identity)
- No re-registration needed with the gateway
- Same node ID across application restarts
- Only `disconnect()` removes the stored connection

This makes your application's network identity stable across restarts!

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
hightower-client = "0.1.4"
```

## Usage

### Basic Connection

```rust
use hightower_client::HightowerConnection;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect with default gateway (http://127.0.0.1:8008)
    let connection = HightowerConnection::connect_with_auth_token("your-auth-token").await?;

    // Access what you need
    println!("Node ID: {}", connection.node_id());
    println!("Assigned IP: {}", connection.assigned_ip());

    // Get transport for communication
    let transport = connection.transport();

    // Use the underlying server for send/receive operations
    // See hightower-wireguard documentation for full API
    // let server = transport.server();

    // Disconnect (automatically deregisters)
    connection.disconnect().await?;

    Ok(())
}
```

### Custom Gateway URL

```rust
use hightower_client::HightowerConnection;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Must specify http:// or https://
    let connection = HightowerConnection::connect(
        "https://gateway.example.com:8443",
        "your-auth-token"
    ).await?;

    println!("Connected to {}", connection.node_id());

    connection.disconnect().await?;

    Ok(())
}
```

## Examples

The library includes several examples:

### Simple Connection
```bash
export HT_AUTH_TOKEN="your-token"
cargo run --example simple_register
```

### Connection Persistence Demo
```bash
export HT_AUTH_TOKEN="your-token"
export HT_GATEWAY_URL="http://127.0.0.1:8008"  # optional
cargo run --example connection_persistence
```

Demonstrates how connections are automatically restored across application restarts.

### Storage Modes
```bash
export HT_AUTH_TOKEN="your-token"
export HT_GATEWAY_URL="http://127.0.0.1:8008"  # optional
cargo run --example storage_modes
```

Shows all available storage modes: default persistence, ephemeral, custom directory, and forced fresh registration.

### Custom Gateway URL
```bash
export HT_AUTH_TOKEN="your-token"
export HT_GATEWAY_URL="https://gateway.example.com:8443"
cargo run --example custom_endpoint
```

### HTTPS Gateway
```bash
export HT_AUTH_TOKEN="your-token"
cargo run --example https_gateway
```

### Auto Deregistration
```bash
export HT_AUTH_TOKEN="your-token"
cargo run --example simple_deregister
```

## API Documentation

### `HightowerConnection`

The main connection struct with integrated WireGuard transport.

#### Methods

- `async fn connect(gateway_url: impl Into<String>, auth_token: impl Into<String>) -> Result<Self, ClientError>`

  Connects to a Hightower gateway with a custom URL. The URL must include the scheme (http:// or https://).

  **With persistence (default):**
  - Checks for existing connection in `~/.hightower/gateway/<gateway>/`
  - If found, restores using stored keys (same identity)
  - If not found, generates new keypair and registers

  Handles everything internally:
  - Generates or restores WireGuard keypair
  - Creates transport server on 0.0.0.0:0
  - Discovers network info via STUN using actual bound port
  - Registers with gateway (or reuses existing registration)
  - Adds gateway as peer
  - Persists connection for future use

  Returns a ready-to-use connection with working transport.

- `async fn connect_with_auth_token(auth_token: impl Into<String>) -> Result<Self, ClientError>`

  Connects using the default gateway (`http://127.0.0.1:8008`). Includes automatic persistence.

- `async fn connect_ephemeral(gateway_url: impl Into<String>, auth_token: impl Into<String>) -> Result<Self, ClientError>`

  Connects without persistence. Always creates fresh registration, nothing stored to disk.

- `async fn connect_with_storage(gateway_url: impl Into<String>, auth_token: impl Into<String>, storage_dir: impl Into<PathBuf>) -> Result<Self, ClientError>`

  Connects using a custom storage directory instead of the default location.

- `async fn connect_fresh(gateway_url: impl Into<String>, auth_token: impl Into<String>) -> Result<Self, ClientError>`

  Forces a fresh registration even if a stored connection exists. Deletes any existing stored connection for this gateway.

- `fn node_id(&self) -> &str`

  Returns the node ID assigned by the gateway.

- `fn assigned_ip(&self) -> &str`

  Returns the IP address assigned by the gateway.

- `fn transport(&self) -> &TransportServer`

  Returns the transport for sending/receiving data.

- `async fn disconnect(self) -> Result<(), ClientError>`

  Disconnects from the gateway and automatically deregisters using the internal token.

### `TransportServer`

Wrapper around the WireGuard transport.

#### Methods

- `fn server(&self) -> &Server`

  Get a reference to the underlying hightower-wireguard `Server`.
  Use this to access the full transport API for sending/receiving data.


### `ClientError`

Error types returned by the library.

**Variants:**
- `Configuration(String)` - Invalid configuration (e.g., empty endpoint, invalid URL)
- `Request(reqwest::Error)` - HTTP request failed
- `GatewayError { status: u16, message: String }` - Gateway returned error
- `InvalidResponse(String)` - Unexpected response format
- `NetworkDiscovery(String)` - Failed to discover network info via STUN
- `Transport(String)` - Transport creation or operation failed
- `Storage(String)` - Storage operation failed (persistence)

## Testing

Run the test suite:

```bash
cargo test
```

## License

MIT