Shadowsocks

https://docs.rs/shadowsocks/latest/
Admin
Shadowsocks is a core library that implements the Shadowsocks proxy protocol, providing secure...
Tokens:178,612
Snippets:1,018
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example: Try Receiving UDP Data

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

An example demonstrating how to use `try_recv_from` in a loop, waiting for the socket to be readable using `socket.readable().await?` and handling `WouldBlock` errors. It prints received data and breaks the loop on success. This example showcases the typical pattern for receiving UDP datagrams asynchronously.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        // The buffer is **not** included in the async task and will
        // only exist on the stack.
        let mut buf = [0; 1024];

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_from(&mut buf) {
            Ok((n, _addr)) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}
```

--------------------------------

### Rust: Wait for Plugin to Start

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/plugin/mod

This function checks if the plugin has successfully started and is listening on its designated port. It supports TCP connections for verification but notes limitations for UDP. The function returns `true` if the plugin is ready within the specified timeout, and `false` otherwise.

```Rust
    /// Check if plugin have been started
    pub async fn wait_started(&self, timeout: Duration) -> bool {
        // Only test started with TCP connect()
        // XXX: Is there an easy way to test if UDP port was listening? (no ICMP!)
        if !self.mode.enable_tcp() {
            return true;
        }

        let start_time = Instant::now();

        loop {
            let now_time = Instant::now();
            let elapsed_time = now_time - start_time;
            if elapsed_time >= timeout {
                return false;
            }
        }
    }
```

--------------------------------

### Rust: Start and Manage Shadowsocks Plugin

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/plugin/mod

This function starts a Shadowsocks plugin subprocess. It determines the local IP for the plugin to listen on based on the remote address. It then attempts to spawn the plugin process, logging success or failure. The function returns a `Plugin` struct containing the process handle and configuration details.

```Rust
    pub fn start(c: &PluginConfig, remote_addr: &ServerAddr, mode: PluginMode) -> io::Result<Self> {
        let loop_ip = match remote_addr {
            ServerAddr::SocketAddr(sa) => match sa.ip() {
                IpAddr::V4(..) => Ipv4Addr::LOCALHOST.into(),
                IpAddr::V6(..) => Ipv6Addr::LOCALHOST.into(),
            },
            ServerAddr::DomainName(..) => Ipv4Addr::LOCALHOST.into(),
        };

        let local_addr = get_local_port(loop_ip)?;

        match start_plugin(c, remote_addr, &local_addr, mode) {
            Err(err) => {
                error!(
                    "failed to start plugin \"{}\" for server {}, err: {}",
                    c.plugin, remote_addr, err
                );
                Err(err)
            }
            Ok(process) => {
                match mode {
                    PluginMode::Client => {
                        debug!(
                            "started plugin \"{}\" on {} <-> {} ({}) {}",
                            c.plugin,
                            local_addr,
                            remote_addr,
                            process.id().unwrap_or(0),
                            c.plugin_mode
                        );
                    }
                    PluginMode::Server => {
                        debug!(
                            "started plugin \"{}\" on {} <-> {} ({}) {}",
                            c.plugin,
                            remote_addr,
                            local_addr,
                            process.id().unwrap_or(0),
                            c.plugin_mode
                        );
                    }
                }

                Ok(Self {
                    process,
                    local_addr,
                    mode: c.plugin_mode,
                })
            }
        }
    }
```

--------------------------------

### Set and Get Server's Source in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

These functions set and get the server's source. `set_source` sets the server's source and `source` retrieves it. Server source may be used for tracking origins.

```Rust
/// Get server's source
    pub fn source(&self) -> ServerSource {
        self.source
    }

    /// Set server's source
    pub fn set_source(&mut self, source: ServerSource) {
        self.source = source;
    }
```

--------------------------------

### Initialize Hickory-DNS System Resolver (Rust)

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/dns_resolver/resolver

Creates and initializes a system DNS resolver using the hickory-dns library. This function supports custom resolver options and connection settings. On Unix-like systems, it asynchronously starts a background task to monitor and reload the resolver when system DNS configurations change.

```rust
impl DnsResolver {
    // ... other methods ...

    /// Use hickory-dns DNS system resolver (with DNS cache)
    ///
    /// On *nix system, it will try to read configurations from `/etc/resolv.conf`.
    #[cfg(feature = "hickory-dns")]
    pub async fn hickory_dns_system_resolver(
        opts: Option<ResolverOpts>,
        connect_opts: ConnectOpts,
    ) -> io::Result<Self> {
        use super::hickory_dns_resolver::create_resolver;

        let resolver = create_resolver(None, opts.clone(), connect_opts.clone()).await?;

        let inner = Arc::new(HickoryDnsSystemResolver {
            resolver: ArcSwap::from(Arc::new(resolver)),
            connect_opts,
            opts,
        });

        cfg_if! {
            if #[cfg(all(feature = "hickory-dns", unix, not(target_os = "android")))] {
                let abortable = {
                    let inner = inner.clone();
                    tokio::spawn(async {
                        if let Err(err) = hickory_dns_notify_update_dns(inner).await {
                            error!("failed to watch DNS system configuration changes, error: {}", err);
                        }
                    })
                };

                Ok(Self::HickoryDnsSystem { inner, abortable })
            } else {
                Ok(DnsResolver::HickoryDnsSystem { inner })
            }
        }
    }

    // ... other methods ...
}
```

--------------------------------

### Start Plugin Command in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/plugin/mod

This function constructs and spawns a child process for a Shadowsocks plugin. It selects the appropriate command generation function (`obfs_proxy::plugin_cmd` or `ss_plugin::plugin_cmd`) based on the plugin name. The function returns a `Result` containing the spawned `Child` process or an `io::Error` if spawning fails.

```rust
fn start_plugin(plugin: &PluginConfig, remote: &ServerAddr, local: &SocketAddr, mode: PluginMode) -> io::Result<Child> {
    let mut cmd = if plugin.plugin == "obfsproxy" {
        obfs_proxy::plugin_cmd(plugin, remote, local, mode)
    } else {
        ss_plugin::plugin_cmd(plugin, remote, local, mode)
    };
    cmd.spawn()
}

```

--------------------------------

### Shadowsocks Network Wrappers Initialization in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/net/mod

This Rust code block serves as the main entry point for the shadowsocks network wrappers module. It uses conditional compilation (`#[cfg(unix)]`) to conditionally import Unix-specific types and re-exports various network-related functionalities, including socket options, IP stack capabilities, and TCP/UDP stream and listener types. This setup allows for platform-specific network handling.

```rust
//! Network wrappers for shadowsocks' specific requirements

use std::net::SocketAddr;

#[cfg(unix)]
pub use self::sys::uds::{UnixListener, UnixStream};
pub use self::{
    option::{AcceptOpts, ConnectOpts, TcpSocketOpts, UdpSocketOpts},
    sys::{IpStackCapabilities, get_ip_stack_capabilities, set_tcp_fastopen, socket_bind_dual_stack},
    tcp::{TcpListener, TcpStream},
    udp::UdpSocket,
};

mod option;
mod sys;
pub mod tcp;
pub mod udp;
```

--------------------------------

### Tokio UdpSocket recv_buf Example

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Demonstrates how to synchronously receive a datagram message into a buffer from a connected UDP socket. This method waits until data is available.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    let mut buf = Vec::with_capacity(512);
    let len = socket.recv_buf(&mut buf).await?;

    println!("received {} bytes {:?}", len, &buf[..len]);

    Ok(())
}
```

--------------------------------

### Tokio UdpSocket try_recv_buf Example

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Demonstrates how to non-blockingly attempt to receive data into a buffer from a connected UDP socket. It handles the `WouldBlock` error and is typically used with `readable().await`.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        let mut buf = Vec::with_capacity(1024);

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_buf(&mut buf) {
            Ok(n) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}
```

--------------------------------

### Async UDP Socket Peek Example (Rust)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Demonstrates how to use `peek_from` to asynchronously receive data from a UDP socket without removing it from the queue. It binds to a local address, prepares a buffer, and prints the number of bytes peeked and the sender's address. This function is part of the `tokio::net::UdpSocket` API.

```Rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    let mut buf = vec![0u8; 32];
    let (len, addr) = socket.peek_from(&mut buf).await?;

    println!("peeked {:?} bytes from {:?}", len, addr);

    Ok(())
}
```

--------------------------------

### Tokio UdpSocket try_recv_buf_from Example

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Demonstrates how to non-blockingly receive a datagram and its origin address. It's useful for server applications that need to handle messages from multiple sources and handles `WouldBlock` errors.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;

    loop {
        // Wait for the socket to be readable
        socket.readable().await?;

        let mut buf = Vec::with_capacity(1024);

        // Try to recv data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match socket.try_recv_buf_from(&mut buf) {
            Ok((n, _addr)) => {
                println!("GOT {:?}", &buf[..n]);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e);
            }
        }
    }

    Ok(())
}
```

--------------------------------

### Bind and Receive UDP Datagrams with Tokio

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Demonstrates how to bind a UdpSocket to a local address and then receive data from a peer. It includes basic error handling and prints the received data length and sender's address. This example is cancel-safe.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;

    let mut buf = Vec::with_capacity(512);
    let (len, addr) = socket.recv_buf_from(&mut buf).await?;

    println!("received {:?} bytes from {:?}", len, addr);

    Ok(())
}
```

--------------------------------

### CryptoStream Initialization and Basic Operations (Rust)

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/relay/tcprelay/crypto_io

Demonstrates the creation of a CryptoStream with different cipher categories (None, Aead2022) and basic stream access methods like getting the underlying stream reference, mutable reference, or consuming the stream to retrieve the inner instance.

```rust
impl<S> CryptoStream<S> {
    // ... constructors for CipherCategory::None and CipherCategory::Aead2022 ...

    /// Return a reference to the underlying stream
    pub fn get_ref(&self) -> &S {
        &self.stream
    }

    /// Return a mutable reference to the underlying stream
    pub fn get_mut(&mut self) -> &mut S {
        &mut self.stream
    }

    /// Consume the CryptoStream and return the internal stream instance
    pub fn into_inner(self) -> S {
        self.stream
    }
}
```

--------------------------------

### Rust Function to Build Obfsproxy Command

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/plugin/obfs_proxy

This Rust function constructs a `tokio::process::Command` object for executing the obfsproxy plugin. It takes plugin configuration, remote and local addresses, and the operating mode (client/server) as input. It handles setting up standard input, kill-on-drop behavior, data directory, plugin-specific options, destination, mode arguments, and any additional plugin arguments. Note that the data directory path is not compatible with Windows.

```Rust
use super::{PluginConfig, PluginMode};
use crate::config::ServerAddr;
use std::{net::SocketAddr, process::Stdio};
use tokio::process::Command;

/// For obfsproxy, we use standalone mode for now.
/// Managed mode needs to use SOCKS5 proxy as forwarder, which is not supported
/// yet.
///
/// The idea of using standalone mode is quite simple, just assemble the
/// internal port into obfsproxy parameters.
///
/// Using manually ran scramblesuit as an example:
/// obfsproxy \
/// --data-dir /tmp/ss_libev_plugin_with_suffix \
/// scramblesuit \
/// --password SOMEMEANINGLESSPASSWORDASEXAMPLE \
/// --dest some.server.org:12345 \
/// client \
/// 127.0.0.1:54321
///
/// In above case, @plugin = "obfsproxy",
/// @plugin_opts = "scramblesuit --password SOMEMEANINGLESSPASSWORDASEXAMPLE"
/// For obfs3, it's even easier, just pass @plugin = "obfsproxy"
/// @plugin_opts = "obfs3"
///
/// And the rest parameters are all assembled here.
/// Some old obfsproxy will not be supported as it doesn't even support
/// "--data-dir" option
pub fn plugin_cmd(plugin: &PluginConfig, remote: &ServerAddr, local: &SocketAddr, mode: PluginMode) -> Command {
    let mut cmd = Command::new(&plugin.plugin);
    cmd.stdin(Stdio::null())
        .kill_on_drop(true)
        .arg("--data-dir")
        .arg(format!("/tmp/{}_{}_{}", plugin.plugin, remote, local)); // FIXME: Not compatible in Windows

    if let Some(ref opt) = plugin.plugin_opts {
        cmd.args(opt.split(' '));
    }

    match mode {
        PluginMode::Client => cmd
            .arg("--dest")
            .arg(remote.to_string())
            .arg("client")
            .arg(local.to_string()),
        PluginMode::Server => cmd
            .arg("--dest")
            .arg(local.to_string())
            .arg("server")
            .arg(remote.to_string()),
    };

    if !plugin.plugin_args.is_empty() {
        cmd.args(&plugin.plugin_args);
    }

    cmd
}
```

--------------------------------

### Rust: Unsafe `unwrap_unchecked` Example

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/udprelay/crypto_io/type

Provides an example of the unsafe `unwrap_unchecked` method, which returns the `Ok` value without checking if the `Result` is `Err`. Calling this on an `Err` results in undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### Shadowsocks Modules Overview (Rust)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/index

This outlines the key modules within the Shadowsocks Rust crate, each responsible for a specific aspect of the Shadowsocks functionality. These modules cover configuration management, service context, DNS resolution, network operations, plugin integration, and the core relay server logic.

```Rust
// config: Configuration management

// context: Shadowsocks service context

// dns_resolver: Asynchronous DNS resolver

// manager: Shadowsocks Server manager

// net: Network wrappers for shadowsocks’ specific requirements

// plugin: Plugin (SIP003)

// relay: Relay server in local and server side implementations.
```

--------------------------------

### Connect to Shadowsocks Server with Options

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Establishes a connection to a Shadowsocks server using provided context, address, and connection options. Returns a UdpSocket instance upon successful connection.

```Rust
pub async fn connect_server_with_opts(
  context: &Context,
  addr: &ServerAddr,
  opts: &ConnectOpts,
) -> Result<Self>
```

--------------------------------

### Shadowsocks Helper Macros (Rust)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/index

This section details helper macros provided by the Shadowsocks Rust crate for common networking tasks. These macros, such as `lookup_then` and `lookup_then_connect`, assist in resolving hostnames and subsequently establishing network connections, simplifying asynchronous operations.

```Rust
// lookup_then: Helper macro for resolving host and then process each addresses

// lookup_then_connect
```

--------------------------------

### Set and Get Server's Mode in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

These functions set and get the server's operational mode. `set_mode` sets the server's mode and `mode` retrieves the current mode. This functionality is crucial for controlling the server's behavior.

```Rust
/// Get server's `Mode`
    pub fn mode(&self) -> Mode {
        self.mode
    }

    /// Set server's `Mode`
    pub fn set_mode(&mut self, mode: Mode) {
        self.mode = mode;
    }
```

--------------------------------

### Rust: Implement From<(String, u16)> for ManagerAddr

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

Provides a conversion from an owned `String` domain name and a u16 port directly to `ManagerAddr::DomainName`.

```rust
impl From<(String, u16)> for ManagerAddr {
    fn from((dname, port): (String, u16)) -> Self {
        Self::DomainName(dname, port)
    }
}
```

--------------------------------

### Implement Blanket Trait: Any

Source: https://docs.rs/shadowsocks/latest/shadowsocks/manager/listener/struct

Implements the Any trait for any type T, providing a way to get the TypeId of an object.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Get underlying stream reference

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/relay/tcprelay/proxy_stream/client

Provides a reference to the underlying stream of the `ProxyClientStream`.

```rust
/// Get reference to the underlying stream
    pub fn get_ref(&self) -> &S {
        self.stream.get_ref()
    }
```

--------------------------------

### Consume ProxyClientStream to get inner stream

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/relay/tcprelay/proxy_stream/client

Consumes the `ProxyClientStream` instance and returns the underlying stream.

```rust
/// Consumes the `ProxyClientStream` and return the underlying stream
    pub fn into_inner(self) -> S {
        self.stream.into_inner()
    }
```

--------------------------------

### Get mutable underlying stream reference

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/relay/tcprelay/proxy_stream/client

Provides a mutable reference to the underlying stream of the `ProxyClientStream`.

```rust
/// Get mutable reference to the underlying stream
    pub fn get_mut(&mut self) -> &mut S {
        self.stream.get_mut()
    }
```

--------------------------------

### Generic ProxyClientStream Connection and Creation Methods

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/proxy_stream/client/struct

Methods for establishing connections and creating ProxyClientStream instances with generic underlying streams, including custom stream mapping.

```APIDOC
## Generic Connection and Stream Creation Methods

### `connect_map`

Connects to a target address via a Shadowsocks server and maps the underlying `TcpStream` to a customized stream.

- **Method**: `async fn connect_map<A, F>`
- **Endpoint**: N/A (Library function)
- **Parameters**:
  - `context` (SharedContext) - Required - Context for the connection.
  - `svr_cfg` (&ServerConfig) - Required - Server configuration.
  - `addr` (A: Into<Address>) - Required - The target address to connect to.
  - `map_fn` (F: FnOnce(OutboundTcpStream) -> S) - Required - A function to map the `TcpStream` to the desired stream type `S`.
- **Returns**: `Result<ProxyClientStream<S>>` where S: AsyncRead + AsyncWrite + Unpin

### `connect_with_opts_map`

Connects to a target address via a Shadowsocks server with options and maps the underlying `TcpStream` to a customized stream.

- **Method**: `async fn connect_with_opts_map<A, F>`
- **Endpoint**: N/A (Library function)
- **Parameters**:
  - `context` (SharedContext) - Required - Context for the connection.
  - `svr_cfg` (&ServerConfig) - Required - Server configuration.
  - `addr` (A: Into<Address>) - Required - The target address to connect to.
  - `opts` (&ConnectOpts) - Required - Connection options.
  - `map_fn` (F: FnOnce(OutboundTcpStream) -> S) - Required - A function to map the `TcpStream` to the desired stream type `S`.
- **Returns**: `Result<ProxyClientStream<S>>` where S: AsyncRead + AsyncWrite + Unpin

### `from_stream`

Creates a `ProxyClientStream` from an already connected underlying stream.

- **Method**: `fn from_stream<A>`
- **Endpoint**: N/A (Library function)
- **Parameters**:
  - `context` (SharedContext) - Required - Context for the connection.
  - `stream` (S) - Required - The pre-connected underlying stream.
  - `svr_cfg` (&ServerConfig) - Required - Server configuration.
  - `addr` (A: Into<Address>) - Required - The target address the stream is connected to.
- **Returns**: `ProxyClientStream<S>` where S: AsyncRead + AsyncWrite + Unpin

**Note**: The provided `stream` must be connected to the server using the same configuration as `svr_cfg`.
```

--------------------------------

### Broadcast Option

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Methods for getting and setting the broadcast option on a socket, allowing the socket to send packets to a broadcast address.

```APIDOC
## `broadcast`

### Description
Gets the value of the `SO_BROADCAST` option for this socket.

### Method
`fn broadcast(&self) -> Result<bool, Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
None

### Request Example
```json
{
  "message": "This method does not have a request body."
}
```

### Response
#### Success Response (200)
- **bool** - `true` if broadcast is enabled, `false` otherwise.

#### Response Example
```json
{
  "broadcast_enabled": true
}
```

## `set_broadcast`

### Description
Sets the value of the `SO_BROADCAST` option for this socket. When enabled, this socket is allowed to send packets to a broadcast address.

### Method
`fn set_broadcast(&self, on: bool) -> Result<(), Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
- **on** (bool) - Required - Set to `true` to enable broadcast, `false` to disable.

### Request Example
```json
{
  "broadcast_enabled": true
}
```

### Response
#### Success Response (200)
- **null** - Indicates the operation was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get Local Address of ManagerDatagram (Rust)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/manager/datagram/enum

Returns the local address to which the ManagerDatagram socket is bound. This is useful for identifying the endpoint of the communication.

```rust
pub fn local_addr(&self) -> Result<ManagerSocketAddr>
```

--------------------------------

### ManagerClient Methods

Source: https://docs.rs/shadowsocks/latest/shadowsocks/manager/client/struct

This section details the methods available on the ManagerClient struct for interacting with the shadowsocks manager.

```APIDOC
## ManagerClient

Client for communicating with Manager.

### Methods

#### `add`

- **Description**: Send an `AddRequest` command to the manager.
- **Method**: `async fn add(&mut self, req: &AddRequest) -> Result<AddResponse, Error>`
- **Endpoint**: Not applicable (internal client method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: `req` (AddRequest) - The request payload for adding an entry.

#### `list`

- **Description**: Send a `ListRequest` command to the manager.
- **Method**: `async fn list(&mut self, req: &ListRequest) -> Result<ListResponse, Error>`
- **Endpoint**: Not applicable (internal client method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: `req` (ListRequest) - The request payload for listing entries.

#### `ping`

- **Description**: Send a `PingRequest` command to the manager.
- **Method**: `async fn ping(&mut self, req: &PingRequest) -> Result<PingResponse, Error>`
- **Endpoint**: Not applicable (internal client method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: `req` (PingRequest) - The request payload for pinging the manager.

#### `remove`

- **Description**: Send a `RemoveRequest` command to the manager.
- **Method**: `async fn remove(&mut self, req: &RemoveRequest) -> Result<RemoveResponse, Error>`
- **Endpoint**: Not applicable (internal client method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: `req` (RemoveRequest) - The request payload for removing an entry.

#### `stat`

- **Description**: Send a `stat` report to the manager.
- **Method**: `async fn stat(&mut self, req: &StatRequest) -> Result<(), Error>`
- **Endpoint**: Not applicable (internal client method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: `req` (StatRequest) - The request payload for the stat report.

#### `connect`

- **Description**: Create a `ManagerDatagram` for sending data to the manager.
- **Method**: `async fn connect(context: &Context, bind_addr: &ManagerAddr, connect_opts: &ConnectOpts) -> Result<Self, Error>`
- **Endpoint**: Not applicable (constructor method)
- **Parameters**:
  - **Path Parameters**: None
  - **Query Parameters**: None
  - **Request Body**: None
  - **Context**: `context` (&Context) - The context for the connection.
  - **Bind Address**: `bind_addr` (&ManagerAddr) - The address to bind to.
  - **Connect Options**: `connect_opts` (&ConnectOpts) - Options for the connection.

### Request Example (Illustrative)
```json
{
  "method": "add",
  "payload": {}
}
```

### Response Example (Illustrative)
```json
{
  "success": true,
  "data": {}
}
```
```

--------------------------------

### Get Mutable Reference to Underlying Stream

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/proxy_stream/client/struct

Returns a mutable reference to the underlying stream (`S`) encapsulated by the `ProxyClientStream`. This allows modifying the stream directly.

```Rust
pub fn get_mut(&mut self) -> &mut S
```

--------------------------------

### TCP Listener from Existing Listener

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/net/tcp

Allows creating a TcpListener instance from an existing tokio TcpListener, with options for TCP FastOpen.

```APIDOC
## POST /api/tcp_listener/from_listener

### Description
Creates a `TcpListener` from a tokio `TcpListener`. Supports enabling TCP FastOpen if configured.

### Method
POST

### Endpoint
/api/tcp_listener/from_listener

### Parameters
#### Request Body
- **listener** (TokioTcpListener) - Required - The existing tokio TcpListener to wrap.
- **accept_opts.tcp.fastopen** (bool) - Optional - Whether to enable TCP FastOpen.

### Request Example
```json
{
  "listener": "<tokio_tcp_listener_handle>",
  "accept_opts": {
    "tcp": {
      "fastopen": true
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of listener creation from existing listener.

#### Response Example
```json
{
  "message": "TcpListener created from existing listener"
}
```
```

--------------------------------

### Get Reference to Underlying Stream

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/proxy_stream/client/struct

Returns an immutable reference to the underlying stream (`S`) encapsulated by the `ProxyClientStream`. This allows inspecting the stream without consuming it.

```Rust
pub fn get_ref(&self) -> &S
```

--------------------------------

### Rust: Get Encryption Method from CryptoStream

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/crypto_io/struct

Retrieves the configured encryption cipher method used by the CryptoStream. This method returns a `CipherKind` enum value.

```rust
pub fn method(&self) -> CipherKind
```

--------------------------------

### Shadowsocks Server Manager Module Overview (Rust)

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/manager/mod

This Rust code snippet defines the main module for the Shadowsocks Server manager. It exports key components like ManagerClient and ManagerListener and declares submodules for client, datagram, error, listener, and protocol management. It serves as the entry point for the manager's functionality.

```rust
//! Shadowsocks Server manager
//! 
//! Service for managing multiple relay servers. [Manage Multiple Users](https://github.com/shadowsocks/shadowsocks/wiki/Manage-Multiple-Users)

pub use self::{client::ManagerClient, listener::ManagerListener};

pub mod client;
pub mod datagram;
pub mod error;
pub mod listener;
pub mod protocol;
```

--------------------------------

### ManagerClient Connection Establishment in Rust

Source: https://docs.rs/shadowsocks/latest/shadowsocks/manager/client/struct

An asynchronous method to establish a connection with the shadowsocks manager. It creates a ManagerDatagram for sending data and requires context, manager address, and connection options.

```rust
pub async fn connect( context: &Context, bind_addr: &ManagerAddr, connect_opts: &ConnectOpts, ) -> Result<Self, Error>
```

--------------------------------

### Generate QRCode and SIP002 URLs in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

These functions generate QRCode and SIP002 URLs for a Shadowsocks server. `to_qrcode_url` generates a URL suitable for a QRCode, while `to_url` generates a SIP002 compliant URL. These URLs are used for easy configuration of clients.

```Rust
/// Get URL for QRCode
    /// ```plain
    /// ss:// + base64(method:password@host:port)
    /// ```
    pub fn to_qrcode_url(&self) -> String {
        let param = format!("{}:{}@{}", self.method(), self.password(), self.addr());
        format!("ss://{}", URL_PASSWORD_BASE64_ENGINE.encode(param))
    }

    /// Get [SIP002](https://github.com/shadowsocks/shadowsocks-org/issues/27) URL
    pub fn to_url(&self) -> String {
        cfg_if! {
            if #[cfg(feature = "aead-cipher-2022")] {
                let user_info = if !self.method().is_aead_2022() {
                    let user_info = format!("{}:{}", self.method(), self.password());
                    URL_PASSWORD_BASE64_ENGINE.encode(user_info)
                } else {
                    format!("{}:{}", self.method(), percent_encoding::utf8_percent_encode(self.password(), percent_encoding::NON_ALPHANUMERIC))
                };
            } else {
                let mut user_info = format!("{}:{}", self.method(), self.password());
                user_info = URL_PASSWORD_BASE64_ENGINE.encode(&user_info)
            }
        }

        let mut url = format!("ss://{}@{}", user_info, self.addr());
        if let Some(c) = self.plugin() {
            let mut plugin = c.plugin.clone();
            if let Some(ref opt) = c.plugin_opts {
                plugin += ";";
```

--------------------------------

### Multicast TTL Option (IPv4)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Methods for getting and setting the `IP_MULTICAST_TTL` option for IPv4 sockets, controlling the time-to-live value of outgoing multicast packets.

```APIDOC
## `multicast_ttl_v4`

### Description
Gets the value of the `IP_MULTICAST_TTL` option for this socket (IPv4).

### Method
`fn multicast_ttl_v4(&self) -> Result<u32, Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
None

### Request Example
```json
{
  "message": "This method does not have a request body."
}
```

### Response
#### Success Response (200)
- **u32** - The current time-to-live value for multicast packets.

#### Response Example
```json
{
  "multicast_ttl": 1
}
```

## `set_multicast_ttl_v4`

### Description
Sets the value of the `IP_MULTICAST_TTL` option for this socket (IPv4). Indicates the time-to-live value of outgoing multicast packets. The default is 1.

### Method
`fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<(), Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
- **ttl** (u32) - Required - The time-to-live value for outgoing multicast packets.

### Request Example
```json
{
  "multicast_ttl": 5
}
```

### Response
#### Success Response (200)
- **null** - Indicates the operation was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Rust: Implement From<(&str, u16)> for ManagerAddr

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

Provides a conversion from a string slice domain name and a u16 port to `ManagerAddr::DomainName` by creating an owned `String` for the domain name.

```rust
impl<'a> From<(&'a str, u16)> for ManagerAddr {
    fn from((dname, port): (&'a str, u16)) -> Self {
        Self::DomainName(dname.to_owned(), port)
    }
}
```

--------------------------------

### Consume ProxyClientStream to Get Inner Stream

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/proxy_stream/client/struct

Consumes the `ProxyClientStream` and returns the underlying stream (`S`). This operation takes ownership of the stream, effectively extracting it from the proxy wrapper.

```Rust
pub fn into_inner(self) -> S
```

--------------------------------

### Get Address Length for SOCKS5 in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/relay/socks5

Calculates the byte length of an `Address` when serialized in the SOCKS5 protocol. This is useful for pre-allocating buffer space or for protocol-level calculations.

```rust
fn get_addr_len(atyp: &Address) -> usize {
    match *atyp {
        Address::SocketAddress(SocketAddr::V4(..)) => 1 + 4 + 2,
        Address::SocketAddress(SocketAddr::V6(..)) => 1 + 8 * 2 + 2,
        Address::DomainNameAddress(ref dmname, _) => 1 + 1 + dmname.len() + 2,
    }
}
```

--------------------------------

### Rust: Bind TcpListener with Accept Options

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/net/tcp

Creates a new `TcpListener` bound to a specific address and configured with accept options. It handles socket creation, and setting send/receive buffer sizes, and TCP Fast Open options based on provided configurations.

```rust
impl TcpListener {
    /// Creates a new TcpListener, which will be bound to the specified address.
    pub async fn bind_with_opts(addr: &SocketAddr, accept_opts: AcceptOpts) -> io::Result<Self> {
        let socket = create_inbound_tcp_socket(addr, &accept_opts).await?;

        if let Some(size) = accept_opts.tcp.send_buffer_size {
            socket.set_send_buffer_size(size)?;
        }

        if let Some(size) = accept_opts.tcp.recv_buffer_size {
            socket.set_recv_buffer_size(size)?;
        }

        // On platforms with Berkeley-derived sockets, this allows to quickly
        // rebind a socket, without needing to wait for the OS to clean up the
        // previous one.
        //
        // On Windows, this allows rebinding sockets which are actively in use,

```

--------------------------------

### ServerConfig New Method (Rust)

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

This associated function creates a new `ServerConfig` instance. It takes the server address, password, and cipher method as input, and uses the `password_to_keys` function to derive the necessary encryption keys. The function returns a `Result` which can be `Ok(Self)` on success or `Err(ServerConfigError)` if key derivation fails.

```rust
pub fn new<A, P>(addr: A, password: P, method: CipherKind) -> Result<Self, ServerConfigError>
where
    A: Into<ServerAddr>,
    P: Into<String>,
{
    let (password, enc_key, identity_keys) = password_to_keys(method, password)?;

    Ok(Self {
        addr: addr.into(),
        password,
        method,
        enc_key,
        identity_keys: Arc::new(identity_keys),
        user_manager: None,
        timeout: None,
        plugin: None,
        plugin_addr: None,
        remarks: None,
        id: None,
        mode: Mode::TcpAndUdp, // Server serves TCP & UDP by default
        weight: ServerWeight::new(),
        source: ServerSource::Default,
    })
}

```

--------------------------------

### Rust: Unsafe `unwrap_err_unchecked` Example

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/udprelay/crypto_io/type

Illustrates the unsafe `unwrap_err_unchecked` method, which returns the `Err` value without checking if the `Result` is `Ok`. Calling this on an `Ok` results in undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

--------------------------------

### Get Port from ServerAddr in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

This function retrieves the port from a `ServerAddr` enum. If the address is a `SocketAddr`, it returns the port. If it's a `DomainName`, it returns the port associated with the domain name.

```Rust
impl ServerAddr {
    /// Get port
    pub fn port(&self) -> u16 {
        match *self {
            Self::SocketAddr(ref s) => s.port(),
            Self::DomainName(_, p) => p,
        }
    }
}
```

--------------------------------

### Create System DNS Resolver (Rust)

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/dns_resolver/resolver

Provides a simple way to create a system DNS resolver. This method relies on the operating system's default DNS configuration, typically resolved via `getaddrinfo` calls executed in a blocking thread pool by Tokio.

```rust
impl DnsResolver {
    /// Use system DNS resolver. Tokio will call `getaddrinfo` in blocking pool.
    pub fn system_resolver() -> Self {
        Self::System
    }

    // ... other methods ...
}
```

--------------------------------

### Create Arc with Custom Allocator and Convert to Raw

Source: https://docs.rs/shadowsocks/latest/shadowsocks/context/type

Demonstrates creating an `Arc` with a specific allocator (`System`) and converting it to raw pointers. It also shows how to reconstruct the `Arc` from the raw pointers and allocator, ensuring memory safety.

```Rust
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;

let x = Arc::new_in("hello".to_owned(), System);
let (ptr, alloc) = Arc::into_raw_with_allocator(x);
assert_eq!(unsafe { &*ptr }, "hello");
let x = unsafe { Arc::from_raw_in(ptr, alloc) };
assert_eq!(&*x, "hello");
```

--------------------------------

### Get Host from ServerAddr in Rust

Source: https://docs.rs/shadowsocks/latest/src/shadowsocks/config

This function retrieves the host from a `ServerAddr` enum. If the address is a `SocketAddr`, it returns the IP address as a string. If it's a `DomainName`, it returns the domain name.

```Rust
impl ServerAddr {
    /// Get string representation of domain
    pub fn host(&self) -> String {
        match *self {
            Self::SocketAddr(ref s) => s.ip().to_string(),
            Self::DomainName(ref dm, _) => dm.clone(),
        }
    }
}
```

--------------------------------

### Rust: Initialize CryptoStream from Stream

Source: https://docs.rs/shadowsocks/latest/shadowsocks/relay/tcprelay/crypto_io/struct

Provides methods to create a new CryptoStream instance from an existing stream. These methods require context, the stream itself, stream type, cipher method, and encryption key. One overload includes identity keys and a user manager for advanced configurations.

```rust
pub fn from_stream( context: &Context, stream: S, stream_ty: StreamType, method: CipherKind, key: &[u8], ) -> Self
```

```rust
pub fn from_stream_with_identity( context: &Context, stream: S, stream_ty: StreamType, method: CipherKind, key: &[u8], identity_keys: &[Bytes], user_manager: Option<Arc<ServerUserManager>>, ) -> Self
```

--------------------------------

### Multicast Loop Option (IPv6)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Methods for getting and setting the `IPV6_MULTICAST_LOOP` option for IPv6 sockets, controlling whether multicast packets are looped back to the local socket.

```APIDOC
## `multicast_loop_v6`

### Description
Gets the value of the `IPV6_MULTICAST_LOOP` option for this socket (IPv6).

### Method
`fn multicast_loop_v6(&self) -> Result<bool, Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
None

### Request Example
```json
{
  "message": "This method does not have a request body."
}
```

### Response
#### Success Response (200)
- **bool** - `true` if multicast loop is enabled, `false` otherwise.

#### Response Example
```json
{
  "multicast_loop_enabled": true
}
```

## `set_multicast_loop_v6`

### Description
Sets the value of the `IPV6_MULTICAST_LOOP` option for this socket (IPv6). If enabled, multicast packets will be looped back to the local socket.

### Method
`fn set_multicast_loop_v6(&self, on: bool) -> Result<(), Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
- **on** (bool) - Required - Set to `true` to enable multicast loop, `false` to disable.

### Request Example
```json
{
  "multicast_loop_enabled": true
}
```

### Response
#### Success Response (200)
- **null** - Indicates the operation was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Multicast Loop Option (IPv4)

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Methods for getting and setting the `IP_MULTICAST_LOOP` option for IPv4 sockets, controlling whether multicast packets are looped back to the local socket.

```APIDOC
## `multicast_loop_v4`

### Description
Gets the value of the `IP_MULTICAST_LOOP` option for this socket (IPv4).

### Method
`fn multicast_loop_v4(&self) -> Result<bool, Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
None

### Request Example
```json
{
  "message": "This method does not have a request body."
}
```

### Response
#### Success Response (200)
- **bool** - `true` if multicast loop is enabled, `false` otherwise.

#### Response Example
```json
{
  "multicast_loop_enabled": true
}
```

## `set_multicast_loop_v4`

### Description
Sets the value of the `IP_MULTICAST_LOOP` option for this socket (IPv4). If enabled, multicast packets will be looped back to the local socket.

### Method
`fn set_multicast_loop_v4(&self, on: bool) -> Result<(), Error>`

### Endpoint
N/A (Method on a socket object)

### Parameters
- **on** (bool) - Required - Set to `true` to enable multicast loop, `false` to disable.

### Request Example
```json
{
  "multicast_loop_enabled": true
}
```

### Response
#### Success Response (200)
- **null** - Indicates the operation was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get Peer Address of Connected UDP Socket

Source: https://docs.rs/shadowsocks/latest/shadowsocks/net/udp/struct

Retrieves the remote socket address to which a connected UDP socket is bound. This is applicable when the socket has been explicitly connected to a peer.

```Rust
pub fn peer_addr(&self) -> Result<SocketAddr, Error>
```

```Rust
use tokio::net::UdpSocket;

let addr = "0.0.0.0:8080".parse::<SocketAddr>().unwrap();
let peer = "127.0.0.1:11100".parse::<SocketAddr>().unwrap();
let sock = UdpSocket::bind(addr).await?;
sock.connect(peer).await?;
assert_eq!(peer, sock.peer_addr()?);
```

--------------------------------

### Rust ServerWeight Trait Implementations

Source: https://docs.rs/shadowsocks/latest/shadowsocks/config/struct

Demonstrates various trait implementations for the ServerWeight struct, including Clone, Debug, and Default. These traits enable functionalities like copying, debugging, and creating default instances.

```rust
impl Clone for ServerWeight {
    fn clone(&self) -> ServerWeight;
    fn clone_from(&mut self, source: &Self);
}

impl Debug for ServerWeight {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

impl Default for ServerWeight {
    fn default() -> Self;
}
```
Tokens:
Raw